Page History

Turn Off History

Almost every commit should have a matching version history entry!

You should always spell check your version history entry! Note that "aspell check filename.tex" is an effective spellchecker on CSL supported machines and will automatically ignore TeX commands.

Note that Condor team members should review our in house notes on version history entries for a few team specific rules.

FAQ

Where's the version history?

It lives in a directory called "version-history" in the manual source. The manual lives in the directory called "doc". If you don't already have a copy of the manual in your source workspace, you can get one with "cvs co -r XXXX-branch doc" where XXXX is the right branch of the manual for your change. 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. We try to keep the individual version sections sorted by relevance. e.g. the first bugs you see in the "Bugs Fixed" section should be the most visible, most important bugs, followed by more and more obscure, less important ones. Same goes for "New Features". Of course, this is subjective, and not the main issue. Better to get it in at all than to worry about the ordering.

What's the right branch of the manual for my change?

See SourceCodeBranches: Active doc branches, or where should my documentation go?.

Does this commit really need a corresponding version history entry?

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

Stuff like that doesn't belong in the version history. Everything else does. Even if it's an extremely obscure bug. Even if you just fixed some dprintf messages in the logs to be more clear. even if you just improved performance or scalability. It doesn't really hurt to have extra entries in the history, and if it becomes a problem, we can always edit out ones that are unnecessary.

What should a version history entry be like?

It should be concise, clear, 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 (not for "security reasons, but because most people reading this won't know anything about our source, even if we were really open). If it's a bug-fix, include the version where the bug was introduced (if you know). It can (and often should) include pointers into other parts of the manual where you document the new config knob, explain the new feature, etc. 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 before the entry, include the GitTrac ticket number or numbers and optionally any relevent commit IDs. 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: 

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

What if i don't know LaTeX?

That's quite alright. 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.