-Almost every commit should have a matching version history entry!
+{section: Version History guidelines}
-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.
+Almost every bug fix or enhancement to the code should have a corresponding Version History entry.
-Note that Condor team members should review {link:http://www.cs.wisc.edu/condor/developers/version-history.html our in house notes on version history entries} for a few team specific rules.
+{subsection: Where's the version history?}
-{section:FAQ}
+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.
+{subsection:What should a version history entry be like?}
-{subsection: Where's the version history?}
+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}".
-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.
+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:
+{code}
+% commit c4f4d911a808e1bdb18552e1cdeb0407b6344969
+\item The default value of
+ \Macro{GRIDMANAGER\_MAX\_SUBMITTED\_JOBS\_PER\_RESOURCE} has
+ changed from 100 to 1000. \Ticket{767}
+{endcode}
-{subsection:What's the right branch of the manual for my change?}
+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.
-See SourceCodeBranches: Active doc branches, or where should my documentation go?.
+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, {link: http://toddshobbies.blogspot.com/2008/01/easy-spell-checking-with-latex.html Todd's Geek Blog shows how to spell check on the fly} just like MS Word.
+{subsection:What's the right branch of the manual for my change?}
-{subsection:Does this commit really need a corresponding version history entry?}
+See SourceCodeBranches - typically it should go in the same branch as the corresponding code.
+
+{subsection: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:
@@ -25,27 +35,11 @@
*: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.
-
-*: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.
+*: 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).
-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.
-
-
-{subsection: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:
-
-{code}
-% #767 commit c4f4d911a808e1bdb18552e1cdeb0407b6344969
-\item The default value of
- \Macro{GRIDMANAGER\_MAX\_SUBMITTED\_JOBS\_PER\_RESOURCE} has
- changed from 100 to 1000.
-{endcode}
+*: 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.
{subsection: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.
+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.
