HTCondorWiki: Version History How To

Page History

Version History Rules and Format

Almost every bug fix or enhancement to the code should have a corresponding Version History entry.

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 Condor 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 Condor'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. 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? but 2) the commit ID becomes mandatory. Here is an example:

% commit c4f4d911a808e1bdb18552e1cdeb0407b6344969
\item The default value of
  \Macro{GRIDMANAGER\_MAX\_SUBMITTED\_JOBS\_PER\_RESOURCE} has
  changed from 100 to 1000. \Ticket{767}

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.

What's 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:

Bug fixes to bugs that were introduced between public releases. e.g. 6.7.9 is out, you add a new features (which SHOULD be in the version history), your new feature breaks something else, you fix the new bug, we ship 6.7.10. No need to document that bug fix, since no one ever saw the bug.
Bug fixes to code that isn't being used, but someday might (e.g. defensive programming).
Anything that there's no way a user or admin could know you changed. For example, you had to refactor a bunch of code to make something shared for another use (the other use probably needs an entry, but the code refactoring does not), or to make it more maintainable. You added a big comment to the source to explain something confusing. You fixed the build system to add -Wall to our compiler flags. You made some part of the code slightly more efficient/scalable without changing semantics of how people use it (of course, significant scalability improvements should be noted).
New features that we specifically do NOT want to be user-visible. e.g. "BIOTECH=true" was never (and should never be) documented in the manual, even the version history.

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.