To cmake and makefile gurus:
My plan is that starting with R14 the version number and copyright date of all Trinity documentation (help files, user guides, etc.) will be the same as the software release.
That way the help files and guides look current rather than look 10 years old. By matching the release date and version, users know which release the documentation belongs and is an indication the documentation is not stagnant with a dumb version number like 0.1.
I will create two entity variables that all related docbook files will use: release date and release version. Therefore the only place we need to update anything would be the entity file and not every single docbook file (ugh). The entity files are part of the tdelibs package.
During the build process is there a way to automatically update these entity variables? I could do that in my own build scripts but I prefer a method that is global to any packager.
How this would work: When a person builds from GIT today and then opens a handbook help file, the date would be today and the release would be R14.0.0 [DEVELOPMENT]. That way all drafts of all documentation show the current date and release number. However, when [DEVELOPMENT] is not part of the version string, that is, with an official release, then the date and release number are always hard-coded to the official release date.
The release version is embedded in the TDE_VERSION_STRING variable in tdelibs/tdecore/tdeversion.h. I don't know whether the release date is hard-coded anywhere. Possibly when detecting that [DEVELOPMENT] is not part of the TDE_VERSION_STRING string, then the release date becomes the file date stamp of tdeversion.h. I'm just speculating and thinking out loud.
Is this possible?
Darrell
On Saturday 18 February 2012 07:11:13 pm Darrell Anderson wrote:
To cmake and makefile gurus:
My plan is that starting with R14 the version number and copyright date of all Trinity documentation (help files, user guides, etc.) will be the same as the software release.
That way the help files and guides look current rather than look 10 years old. By matching the release date and version, users know which release the documentation belongs and is an indication the documentation is not stagnant with a dumb version number like 0.1.
I will create two entity variables that all related docbook files will use: release date and release version. Therefore the only place we need to update anything would be the entity file and not every single docbook file (ugh). The entity files are part of the tdelibs package.
During the build process is there a way to automatically update these entity variables? I could do that in my own build scripts but I prefer a method that is global to any packager.
How this would work: When a person builds from GIT today and then opens a handbook help file, the date would be today and the release would be R14.0.0 [DEVELOPMENT]. That way all drafts of all documentation show the current date and release number. However, when [DEVELOPMENT] is not part of the version string, that is, with an official release, then the date and release number are always hard-coded to the official release date.
The release version is embedded in the TDE_VERSION_STRING variable in tdelibs/tdecore/tdeversion.h. I don't know whether the release date is hard-coded anywhere. Possibly when detecting that [DEVELOPMENT] is not part of the TDE_VERSION_STRING string, then the release date becomes the file date stamp of tdeversion.h. I'm just speculating and thinking out loud.
Is this possible?
We would probably need a few people to make sure that documentation is up-to-date with what is currently in 3.5.13 (for example, was the documentation updated when the TMenu search box was added?), and then to make sure it is still up-to-date with new changes/features from R14 on.
I don't yet know much about git, but would it be possible to have a script built in to the server so that when it comes time to release, and development is copied over to stable branch, your variable is updated in stable only? Also, would there be a way of having Tim's quickbuild set it in the nightly builds?
If that is possible, then packagers who are using development would still have to set it in their own development branch packages, but the stable release and nightlies for Debian/Ubuntu would be already set.
We would probably need a few people to make sure that documentation is up-to-date with what is currently in 3.5.13 (for example, was the documentation updated when the TMenu search box was added?), and then to make sure it is still up-to-date with new changes/features from R14 on.
I believe no documentation has been updated with any of the changes made after 3.5.10. :(
I have been thinking about this process for many weeks. I believe this topic ties into our recent discussions about having a review board. The bugzilla seems to be a possible avenue to trigger reviews, but often code patches are committed to the source code without a formal bug report. How do we monitor those commits for documentation reviews?
Perhaps somebody (preferably two or more people) as part of a documentation review team. Perhaps this team reviews the GIT patch logs on a daily or weekly basis and then populates a punch list somewhere to note which documentation files need updating.
If we do something like that then we need to be serious about documentation. That is, documentation that is not updated becomes a release blocker. I've been in the tech writing business many years and if documentation is not elevated to Blocker status then you can guess what happens. :)
Currently we have no process to ensure documentation is reviewed and updated. We need a way to encourage documentation reviews.
How do folks with other software projects handle this?
I don't yet know much about git, but would it be possible to have a script built in to the server so that when it comes time to release, and development is copied over to stable branch, your variable is updated in stable only? Also, would there be a way of having Tim's quickbuild set it in the nightly builds?
If that is possible, then packagers who are using development would still have to set it in their own development branch packages, but the stable release and nightlies for Debian/Ubuntu would be already set.
Hmm, perhaps the easiest way is to have a short shell script update the related files with each GIT HEAD update. Anybody who downloads GIT sources would have the date and release version hard-coded into the entity file. When official tarballs are released, the same entity file is hard-coded with the same information. People who generate their own tarballs have the same data frozen from the day they downloaded the sources from GIT. A shell script at the main GIT repository is the cleanest way to go. Just update the affected entity file with every HEAD update.
Tim, I haven't yet decided where I will store those entity variables, but down the road does a shell script sound doable?
Darrell
On Saturday 18 February 2012 08:24:14 pm Darrell Anderson wrote:
We would probably need a few people to make sure that documentation is up-to-date with what is currently in 3.5.13 (for example, was the documentation updated when the TMenu search box was added?), and then to make sure it is still up-to-date with new changes/features from R14 on.
I believe no documentation has been updated with any of the changes made after 3.5.10. :(
I have been thinking about this process for many weeks. I believe this topic ties into our recent discussions about having a review board. The bugzilla seems to be a possible avenue to trigger reviews, but often code patches are committed to the source code without a formal bug report. How do we monitor those commits for documentation reviews?
Perhaps somebody (preferably two or more people) as part of a documentation review team. Perhaps this team reviews the GIT patch logs on a daily or weekly basis and then populates a punch list somewhere to note which documentation files need updating.
If we do something like that then we need to be serious about documentation. That is, documentation that is not updated becomes a release blocker. I've been in the tech writing business many years and if documentation is not elevated to Blocker status then you can guess what happens. :)
Currently we have no process to ensure documentation is reviewed and updated. We need a way to encourage documentation reviews.
How do folks with other software projects handle this?
I think the easiest way to do this is to have those with commit access keep a running list (possibly on the Etherpad) of what they are changing that would entail a documentation update. Obviously, a bugfix that doesn't change or add any features would not require updated documentation -- most such bugfixes are simply to help with crashes, security, and general stability. Instead, the list would only changes that occur at the user-visible level (i.e. feature changes and additions).
One problem to consider with the documentation team is that not everybody will use every program. For example, not everybody will use KDevelop (TDevelop?) because not everybody will be developing TDE apps. I'd suggest we have people assigned to programs they actually use. Of course, we'd have to account for when someone doesn't use every possible feature of an app they do use, e.g. if someone chooses to use Konqueror instead of Amarok to sync their music to their PMP (most PMPs show up as a flash drive).
-
Darrell Anderson -
Kristopher John Gamrat