Version references in documentation

Yawar Amin 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. [1]

> 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?

Regards,

Yawar

[1] 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...
Name: PGP.sig
Type: application/pgp-signature
Size: 194 bytes
Desc: This is a digitally signed message part
URL: <http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20100826/adc30776/attachment.bin>


More information about the gnucash-devel mailing list