Version History Rules and Format

Almost every bug fix or enhancement to the code should have a corresponding Version History entry in the Manual. This document should answer all questions re how the project will maintain this important information.

Where's the version history?

It lives in the source code in /doc/version-history. Inside version-history, there are separate files for each release series (e.g. 6-7.history.tex). In each file, there's a separate subsection for each version, with the most recent versions at the top of the file. Try to keep the individual version sections sorted by relevance.

What should a version history entry be like?

It should be concise, clear, self-contained English prose. It should be just enough info for a user or admin to have an idea of the kind of change, so they can decide if they care enough about it to upgrade their pool. It should not include any developer jargon, or refer to internals of the HTCondor source because people shouldn't have to know anything about our source. It should be short - if it is more than a couple sentences, or includes tables/lists, you should place this new information elsewhere in the manual. The version history entry can then (and often should) include pointers into other parts of the manual where you document the new config knob, explain the new feature, etc. So for instance, if you fix a bug in the file transfer code, it doesn't hurt to include the line: "For more information about HTCondor's file transfer capabilities, see section~\ref{sec:file-transfer}".

Immediately at the end of the entry, include the gittrac ticket number associated with this change by using the \Ticket macro as in the example below - note there is no trailing period after invoking this macro. And, this macro goes on its own line in the LaTeX source. Optionally it is nice to include a commit ID as a comment above the entry. If you don't have a gittrac ticket number, 1) why not create a ticket and use it? or2) the commit ID becomes mandatory. Here is an example:

% commit c4f4d911a808e1bdb18552e1cdeb0407b6344969
\item The default value of
  changed from 100 to 1000.

Note - users should not have to refer to the gittrac ticket to understand the change at a basic level. For instance, an entry like "Fixed a bug in the schedd Ticket XXXX" is not acceptable.

Like any text added into the Manual, you should always spell check! Note that "aspell check filename.tex" is an effective spellchecker on CSL supported machines and will automatically ignore TeX commands. If you use Vim or Emacs, Todd's Geek Blog shows how to spell check on the fly just like MS Word.

Like any commmit, your changes should not break the build. In this case, we're talking about a build of the manual. Check your prose, your formatting, and that you have not broken the build by making the manual. Two convenient targets are in /doc/Makefile: 1) ref.pdf will make a pdf called ref.pdf, and 2) local.html will place html files in a directory named ref-v<version>.

What is the right branch of the manual for my change?

See SourceCodeBranches - typically it should go in the same branch as the corresponding code.

Does my code change really need a corresponding version history entry?

In general, the answer is 'yes'. The only things that should not be in the history are:

What if I don't know LaTeX?

Any staff member who does know latex would be happy to help you get your version history into the Manual. You can always ask Karen for help. In the long term, however, plan on learning LaTeX as at least all members of the core development team are expected to also be capable of documenting their changes in the Manual.

Using Git to determinine where version history goes

This is pretty easy, if the Gittrac ticket number is in the corresponding commit message.

First, you find which commits holds the relevant ticket: so to find the commits pertaining to #2004, you do

git log --oneline --grep=2004 --all

This will produce a list:

85bad3f Ticket #2004: Update param table w/SHADOW_RUN_UNKNOWN_USER_JOBS
14f8eed Ticket #2004: Allow priv switching on shadow to nobody when SHADOW_RUN_UNKNOWN_USER_JOBS=TRUE.  By default it is off.
<Irrelevant stuff...>

From this log, it looks like 85bad3f and 14f8eed are the relevant commits, and there are others listed that are not pertinent. (If the ticket numbers are not in the commit message, the git log command is useless for this.)

Now you can do (for some reason, git tag --contains takes longer than it should...)

git tag --contains 85bad3f | grep -E '^V[[:digit:]]+_[[:digit:]]+_[[:digit:]]+$'
which produces the list
Thus we know the feature (or bugfix) in #2004 was first released in 7.6.1.