- 1 Tips for making good commits
- 1.1 Never commit code that doesn't validate
- 1.2 Double check what you commit
- 1.3 Always add descriptive log messages
- 1.4 Respect other coordinator's code
- 1.5 Announce changes in advance
- 1.6 Take responsibility for your commits
- 1.7 Don't commit code you don't understand
- 1.8 Don't commit if other developers disagree
- 1.9 Backport bugfixes
- 1.10 Tags and branches
- 1.11 Don't use SVN keywords in source files
- 1.12 Make "atomic" commits
- 1.13 Don't mix formatting changes with code changes
- 1.14 Have a clear commit message
- 2 Add new files
- 3 Review process
Tips for making good commits
Never commit code that doesn't validate
Validate the code (XSD-files) and examples (XML-files) together. Correct all errors before committing. Make sure that newly added files are committed. If they are missing, your local validation will work fine, but everybody else won't be able to validate without errors.
Double check what you commit
svn update and a
svn diff before committing. Take messages from SVN about conflicts, unknown files, etc. seriously.
svn diff will tell you exactly what you will be committing. Check if that's really what you intended to commit.
Always add descriptive log messages
Log messages should be understandable to someone who sees only the log. They shouldn't depend on information outside the context of the commit. Try to put the log messages only to those files which are really affected by the change described in the log message. In particular put all important information which can't be seen from the diff in the log message.
Respect other coordinator's code
Consult other developers before making large changes. Source control systems are not a substitute for developer communication.
Announce changes in advance
When you plan to make changes which affect a lot of different code in SVN, announce them in the newsgroup in advance. By announcing the changes in advance, developers are prepared, and can express concerns before something gets broken.
Take responsibility for your commits
If your commit breaks something or has side effects on other code, take the responsibility to fix or help fix the problems.
Don't commit code you don't understand
Avoid things like "I'm not completely sure if that's right, but at least it works for me." If you don't find a solution to a problem, discuss it with other developers.
Don't commit if other developers disagree
If there are disagreements over code changes, these should be resolved by discussing them in the newsgroup or in private (e-mail or phone), not by forcing code on others by simply committing the changes to SVN.
If you commit bugfixes, consider porting the fixes to other branches. Use the same comment for both the original fix and the backport, that way it is easy to see which fixes have been backported< already.
Tags and branches
Official railML branches and release tags will be created by the release coordinator in the branches/ and tags/ directories. All temporary working branches (which should be deleted again after the work has ended) should be located in branches/ with some name describing both which part of railML is branched and which work is done there, e.g. branches/timetable-duty.
Don't use SVN keywords in source files
SVN keywords like
Log cause unnecessary conflicts when merging branches and don't contain any information which wouldn't be available in the SVN repository anyway.
Make "atomic" commits
SVN has the ability to commit more than one file at a time. Therefore, please commit all related changes in multiple files, even if they span over multiple directories at the same time in the same commit. This way, you ensure that SVN stays in a validable state before and after the commit. Consider changing example files in the repository.
Don't mix formatting changes with code changes
Changing formatting like indenting or white spaces blows up the diff, so that it is hard to find code changes if they are mixed with re-indenting commits or similar things when looking at the logs and diffs later. Committing formatting changes separately solves this problem.
Have a clear commit message
Honoring Dev:Coding_XML_Components and Dev:Syntactic_Guidelines, write commit messages in English. The first line of commit is a summary of the changes. The rest of the message should give more details on the change as appropriate. Give credit where credit is due.
Add new files
If you add a new file to the SVN repository, you have to set the proper SVN properties for the new file and add some SVN keywords to your file.
SVN properties for XML and XSD files
svn propset svn:keywords Id $FILE svn propset svn:eol-style native $FILE svn propset svn:mime-type text/xml $FILE
SVN properties for HTML files
svn propset svn:keywords Id $FILE svn propset svn:eol-style native $FILE svn propset svn:mime-type text/html $FILE
SVN properties for image files
svn propset svn:mime-type image/png $FILE
svn propset svn:mime-type image/jpeg $FILE
Insert SVN keyword
Id SVN keyword into a comment line on top of the new file.
<?xml version="1.0" encoding="UTF-8"?> <!-- $Id$ --> ...
This is expanded prior to your commit by the SVN server with the according data, e.g.
<!-- $Id: genericRailML.xsd 405 2011-06-15 10:04:53Z susanne.wunsch $ -->
Id keyword shows current file name, SVN revision number, date, time and commiter.
Pretty print HTML-files
For pretty printing HTML files which are auto-generated after some important code change please use
tidy with the following parameters:
tidy -wrap 20000 -m -i $FILE
Commits are reviewed by the railML coordinators. In case of commits, non-conformant with these guidelines, railML coordinators have to fix the situation with a commit indicating the correction in the log message.