19 Feb
2012
19 Feb
'12
12:11 a.m.
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
19 Feb
19 Feb
12:44 a.m.
New subject: [trinity-devel] Publishing help files, user guides, etc.
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.
--
Kris Gamrat
Ark Linux webmaster
http://www.arklinux.org/
1:24 a.m.
New subject: [trinity-devel] Publishing help files, user guides, etc.
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
3:55 a.m.
New subject: [trinity-devel] Publishing help files, user guides, etc.
On Saturday 18 February 2012 08:24:14 pm Darrell Anderson wrote:
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).
--
Kris Gamrat
Ark Linux webmaster
http://www.arklinux.org/
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?
4708
days inactive
4708
days old
3 comments
2 participants
participants (2)
-
Darrell Anderson -
Kristopher John Gamrat