19 Feb
2012
19 Feb
'12
1:24 a.m.
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