Dev:Git Guidelines
Tips for making good commits
Master/development branches
Only commit to the master branch directly if the changes your are commiting are complete in themselves and don't change the syntax of railML. Changes to the syntax of railML should be isolated in a development branch, such as railML-2.5-dev and merged back to master along with the necessary documentation upon release of a new version. Changes, such as changes to the registers, the xsd documentation or the html documentation are permitted to be commited on master.
Create feature branches when developing complex changes
Since complex changes usually are done in more than a single commit it is best to isolate them in a feature branch as to not contaminate the branches that are of a more general nature with intermediate solutions. Merge back your changes when you are sure everything is in order, validating and discussed with your team members. Merging back should take place with a pull request that can be issued via https://development.railml.org/railml/version2/-/merge_requests and https://development.railml.org/railml/version3/-/merge_requests respectively.
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. You can easily check this with the command git status.
Double check what you commit
Stage your changes carefully and review the changes before commiting. You can for example easily do that using git gui. If you made changes that are related to different issues in the same file please also consider to stage/unstage only certain chunks/lines of your changes that relate to a single issue.
Carefully resolve conflicts
If you cannot push your commits and run into conflicts when reintegrating the remote state into your local git, take your time to carefully resolve conflicts that may arise. Other commiters may have also added valuable content so simply resolving a conflict by rejecting "Theirs" is not a solution. If necessary contact the other comitters to find a solution.
Always add descriptive log messages
Commit messages should be understandable to someone who sees only the history. They shouldn't depend on information outside the context of the commit. Try to put the log messages only to those files and lines 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, most importantly why a certain change was done and was necessary.
Reference issue trackers
When commiting include a reference to an issue from the issue tracker at https://development.railml.org/railml/version2/-/issues or development.railml.org/railml/version3/-/issues in the commit message. You can do so by simply mentioning the issue number prefixed with a #, e. g. #42
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 the repository, announce them in the newsgroup in advance. By announcing the changes in advance, developers are prepared, and can express concerns before something gets broken. Prepare those changes in a branch and have others take a look at your proposed solution so that no intermediate states find their way to the more general branches.
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 the repository.
Backport bugfixes
If you commit bugfixes, consider porting the fixes to other branches. The easiest way to do that is you using a cherry-pick. You can do this on the command line or with various graphical tools. The git setup comes with gitk --all that easily allows this. Switch to the branch you want to apply the bugfix to, run gitk --all, select the commit from the other branch (where you already fixed the problem), right-click and select "Cherry-pick". Resolve potential conflicts.
Tags and branches
Apart from the master all official railML branches and tags are named so that they start with "railML". For new feature branches the prefix "feature-" shall be used.
Make "atomic" commits
Repository 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 the repository stays in a validable state before and after the commit. Consider changing example files in the repository. If changes to a file address multiple issues please split them by only staging some of the changes in a file for commit and isolate changes in separate commits if they do now belong together.
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
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. Please do not forget to include the reasoning for the change. This will help understanding the code later.
Review process
Commits are reviewed by the railML coordinators. In order to have railML coordinators review your changes please issue a merge request via https://development.railml.org/railml/version2/-/merge_requests or https://development.railml.org/railml/version2/-/merge_requests. 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.