Documenting unreleased features in the guide

Rainer Müller raimue at
Sat May 17 18:11:09 PDT 2008

Hi all,

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 
different solutions:

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.

Other ideas?


More information about the macports-dev mailing list