Documenting unreleased features in the guide
raimue at macports.org
Sat May 17 18:11:09 PDT 2008
at the moment, we do not distinguish between features in the released
version and features on trunk only (e.g. universal_archs, sort
master_sites by ping) in our guide. This will easily lead to confusion
by users. Therefore we need some way to ensure users get the right
documentation and do not make wrong assumptions because they read about
stuff which is only in trunk. Also, stuff on trunk might change until it
is finally released.
I think there are multiple ways to deal with this problem. Here are two
1) Branch the guide to the release branch
This means multiple trees of the guide exist. While new features are
being documented on trunk, fixes to the existing documentation are
merged back to the release branch. Might lead into some work to do the
nominating and merging stuff.
2) Include version information directly in the guide
There is still only one tree of the guide. Every new feature and
variable documented has a version number. This will just be a smaller
printed information after the variable name or below the section
headline, something like ">=1.7.0" or "HEAD only".
I already had some words about this on IRC with Joshua and Bill (who
actually suggested number 2). Personally, my first idea was way 1, but
after some thinking I like way 2 better. As our guide is always
work-in-progress, I think this will be a good way to reflect the current
state how things work according to the version information.
More information about the macports-dev