-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Hi Joe, Bill, All,
I work on several open-source doc projects using LaTeX, DocBook, Mallard, Standard XML, etc., and for the most part, one thing holds true across all of them, the docs follow the release, and are frozen at that release level / version. I don't recall having seen a situation where docs were committed back into a previous release tag / branch, rather, the edits / updates were put forward to maintenance releases like Bill stated e.g. branch/v1.3.1, branch/1.3.2 etc., then a new branch created for the next major release level from that last tagged release. If the intention is to use Web-Based user documentation as the primary help source, this makes things easy, separate application source code from documentation source code. If the need is to have the system documentation match online docs, then AsciiDoc is not the right tool for the job. Documentation, for the most part, always lags development for obvious reasons, unless there's some sort of release schedule that builds in time fort writing. So no matter which form the documentation takes, PDF, Xml, Sgl, DocBook, LaTeX, HTML, epub whatever, the same problem exists. If pulling documentation into application build is an issue, then I suggest we do not pull it at all or change to some other form of documentation that lends itself to that type of process. However, content will still need updating no matter which tool is used. 73's Greg, KI7MT [email protected] On 2/3/2014 17:42, Bill Somerville wrote: > On 03/02/2014 17:15, Joe Taylor wrote: >> Hi all > Hi Joe & All, >> >> Thanks to Bill for the reminder and good advice about committing >> an SVN Tag for our released Version 1.3, r3673. I have now done >> so. > OK. >> >> Bill, any time you're ready to do so, feel free to commit your >> new setup and rig-control code. Subsequent development (of what >> will be v1.4, or 2.0, or whatever) should continue to take place >> in the .../branches/wsjtx directory. > Will try and commit soon, it will be a big change. I need to go > through everything and tie up any loose ends first. >> >> If necessary, any bug fix or minor tweak to v1.3 should be done >> in the newly created .../tags/wsjtx-1.3 branch. (But this should >> be resisted, if possible.) New work should definitely go into >> .../branches/wsjtx. > Normally .../tags/... should not be committed to. Instead make a > new branch ../branches/... by copying the tag to something like > .../branches/wsjtx-1.3.1/... and then commit fixes to there with > merges into .../branches/wsjtx/... if appropriate. >> >> How best to handle documentation revisions? They are still very >> much in progress, even for Version 1.3. >> >> I suggest that doc revisions should continue to be committed to >> .../branches/wsjtx, the development branch, until version 1.4 >> (or 2.0?) becomes usable as a beta release. Then we can put a >> new snapshot of docs into the .../tags/wsjtx-1.3 branch, and >> start making further documentation changes -- in particular, >> things that will be different in v1.3 and v1.4 -- in the >> development branch. >> >> Does this make sense? Is there a better way? > I know there was some discussion on documentation and code lines > before. I'm not sure what the best options are. The following > thoughts come to mind: > > 1) If we are only going to publish the docs via the web site then > perhaps they should be treated as a separate project with > milestones in parallel with program releases. Then extra > "documentation only" releases could be made to fix and extend the > docs. > > 2) Despite (1) it might be nice to include the docs with a release > bundle, particularly for the benefit of offline users. > > 3) (2) is an issue with me for the CMake scripts as I intend them > to do packaging and the pre-requisites for the docs build might be > more than most developers might want to fight with. This is > especially true if for example we choose to ship a PDF of the docs > - asciidoc -> PDF needs a lot of packages installed. I see Cygwin > is already in the mix on Windows and this might be tricky to > automate builds using both MinGW and Cygwin. > > 4) We need to take care branching the docs code line. Merges of > documentation are not easy to check and errors can creep in. It > might be worth banning merges and require that documentation fixes > be applied manually to all relevant branches. Conversely exactly > the opposite is best practice for source code line branches! >> >> -- Joe, K1JT > 73 Bill G4WJS. >> >> >> When V1.3 users call up the online documentation, they now see >> the stuff I committed this morning, r3684. I could >> >> I think that means we should right now start committing >> documentation changes to the .../tags/wsjtx-1.3 branch, >> >> As soon as the main development branch starts to have features >> that conflict with the present User's Guide -- for example, a >> Setup | Configuration screen that looks different -- we' >> >> On 1/31/2014 4:45 PM, Bill Somerville wrote: >>> On 31/01/2014 20:50, Joe Taylor wrote: Hi Joe, >>>> John -- >>>> >>>> John Nelson wrote: >>>>> I have downloaded r3673 and it is running undertest - but I >>>>> notice you have made improvements regarding Type 1 and 2 >>>>> messages and genStdMsgs() - but this is r3677. >>>>> >>>>> Do want these improvements to be excluded from the new >>>>> release? >>>> >>>> I agree it seems slightly awkward, but I decided this morning >>>> to release the well-tested code (r3673) and then make the >>>> mods for auto-generation of messages with complex callsigns. >>>> So yes, I'm recommending that the released version be 3673. >>> It is best practice to tag milestones like releases in the >>> repo. For example the command (assuming you use ssh access to >>> the repo): >>> >>> svn copy -r 3673 >>> svn+ssh://[email protected]/svnroot/repos/wsjt/branches/wsjtx >>> >>> svn+ssh://[email protected]/svnroot/repos/wsjt/tags/wsjtx-1.3 -m >>> "Tagging WSJT-X release version" >>> >>> will tag r3673 for ever more as the 1.3 release of WSJT-X. >>> >>> That way there is no need to remember which revision represents >>> a milestone and later defect fix release branches can be >>> created by copying the tag back to 'branches'. >>> >>> svn copy is cheap in that no actual files are copied on the >>> server, only changes to files use 'file space'. >>> >>> More complex tags can be created if required, for example the >>> discussion on kvasd binaries is relevant in that the revisions >>> of kvasd used for the release could also be included in the tag >>> by using the more comprehensive "build a workspace from various >>> revisions and tag the workspace contents" version of svn copy. >>> Having said that the svn:externals property is a much better >>> way of handling mapping of external files from elsewhere in a >>> repo to a tree in a repo and would suit the kvasd situation >>> where the binaries are used in multiple projects. >>>> >>>> -- Joe >>> 73 Bill G4WJS. _______________________________________________ >>> Wsjt-devel mailing list [email protected] >>> https://lists.berlios.de/mailman/listinfo/wsjt-devel >> _______________________________________________ Wsjt-devel >> mailing list [email protected] >> https://lists.berlios.de/mailman/listinfo/wsjt-devel > > _______________________________________________ Wsjt-devel mailing > list [email protected] > https://lists.berlios.de/mailman/listinfo/wsjt-devel -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.22 (MingW32) Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQEcBAEBAgAGBQJS7+e9AAoJEAmfcyeKlj0xUZsH/RKGTrqPFxKJx/Y4nJQXNTrf YO3R1Rvs4z9uLHSohMiJ0kt6Y4IlAJz8eMWkAXF/T+5Phzcnn/MAz4+MUKf4VxjW pq+DDNu4hqLpM72Q7Bl4C6JpscYHDfLXNIRXlsL6KA0/Sk/zHCkATAmaOFR0XqzF hFtWHh3FSo8EP230NVYgL+KoOm/RYN4IWffL+zXHXFemeBxl+drWrRNR0c+LMOO6 r6r3Ka5dOMkmZPIbgZANC4k610s7RYgcV+zyMrm41O737seLc+XT1KHhU6WXtGFe 6hHV1CjCzpI1NAbZ/D0BqOy5Q8vuq3wTA8ay4QLzo39K1ts6D4WrKZQa9ipJ85I= =8O1v -----END PGP SIGNATURE----- _______________________________________________ Wsjt-devel mailing list [email protected] https://lists.berlios.de/mailman/listinfo/wsjt-devel
