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
\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.
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:
- 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 is no way a user or administrator 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.
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:]]+$'
V7_6_1 V7_6_2 V7_7_0