Version references in documentation
yawar.amin at gmail.com
Thu Aug 26 00:14:08 EDT 2010
On 2010-08-25, at 08:47, Geert Janssens wrote:
> Hmm, in my opinion this would not be as useful as using parameter entities to
> define current-stable, next-stable and so on.
> gnucash-docs' trunk is not meant to apply to all versions of GnuCash. It
> should only apply to the trunk version of GnuCash. Documentation releases are
> targeted at a specific GnuCash release. Each of these documentation releases
> will get its own tagged revision. So there's not really a need for
> conditionals based on the GnuCash release.
OK, if we keep version-specific changes in separate branches, it's definitely simpler to not use conditionals.
> If documentation updates are offered specific to a tagged documentation
> release, that don't apply to the trunk version of the documentation, a
> documentation branch can be created holding these specific documentation
> updates. This branch can also be the basis for new documentation releases.
If I'm understanding this right, to maintain documentation for x versions of GnuCash, we'll need x + 1 branches (see below).
> Perhaps an example will clear this up:
> gnucash-docs trunk is currently targetted at gnucash (the code) trunk.
> The documentation that goes with GnuCash 2.2.9 is tagged 2.2.
> Suppose someone posts a change to the documentation, but this new
> documentation is only valid for GnuCash 2.2.9, and doesn't apply to the
> current development series. Then a branch should be made in svn for the 2.2
> documentation and the changes will be applied there. At some point, this
> branch will then be released (tagged) as version 2.2.1 for gnucash-docs.
> Suppose then someone adds documentation that is relevant for both 2.2.9 and
> 2.3.x/2.4. This should be added to trunk and from there on merged into the 2.2
> branch as well. This would lead to two separate documentation releases, 2.2.2
> (for the 2.2.x series) and 2.4.x when GnuCash 2.4 is eventually released.
OK, I may have a slightly different model in mind: when a 2.2.9-specific change is made, it can go into a 2.2 branch; and when a trunk-specific change is made, it can go into trunk; but when a general (that is, not specific to a version) change is made, it needs to go into a `general' branch, and this `general' branch always needs to be a parent of the other branches.
So for example if a general typo is fixed in the `general' branch, then we can just merge that change into the 2.2 branch and into trunk. 
> So again, I'm not in favor of using parameter entity based conditionals in the
> documentation source. Svn itself will allow proper separation of 2.2.x and
> 2.4.x documentation sources.
That said, I can do all this branching and merging stuff fairly easily in Git. But honestly SVN branching and merging scare me a little. Given these branching rules, can we implement a tight system to keep version-specific changes separate?
 Another possible model is to designate trunk as the `general' branch for non-version-specific changes, 2.2 as a maintenance branch for the 2.2.x series, 2.3 as the development branch for the unstable 2.3.x series, and so on.
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 194 bytes
Desc: This is a digitally signed message part
More information about the gnucash-devel