Difference between revisions of "Commit Guidelines"

Jump to navigation Jump to search
4,039 bytes removed ,  07:21, 29 April 2016
(→‎Rules: Tweak ALL description per LordHoto's suggestion)
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
In the past, ScummVM was quite lax on commit message formatting. Well, we won't start beating people up, but everyone should at least all be aware of the issue at hand; namely, what distinguishes good commit messages from bad ones. This page hopes to help all of us to improve our commit messages a bit... The benefit will be to the full team as commit logs will be more readable.  
This page contains some guidelines about commits and commit messages.


== Rules ==
== Commit guidelines ==
Thus the rules are following (they're standard to git except SUBSYSTEM thing):
 
Commits shouldn't contain multiple unrelated changes; try and make piecemeal changes if you can, to make it easier to review and merge. In particular, don't commit style/whitespace changes and functionality changes in a single commit.
 
If you change shared common code, then (while not necessarily in the same commit, due to the above guideline!) you should also make at least a best-effort attempt to make sure all of the engine/backend code stays working.
 
Assure that ScummVM compiles with every commit. In case of regressions, this helps to track down the commit introducing the regression.
 
== Commit message formatting ==
We won't start beating people up, but everyone should at least all be aware of the issue at hand; namely, what distinguishes good commit messages from bad ones. This page hopes to help all of us to improve our commit messages a bit... The benefit will be to the full team as commit logs will be more readable.
 
The rules on commit messages are the following (they're standard to git, except our SUBSYSTEM requirement):
<pre>
<pre>
SUBSYSTEM: Short (50 chars or less) summary of changes
SUBSYSTEM: Short (50 chars or less) summary of changes
Line 31: Line 41:
The subsystem names which were used so far:
The subsystem names which were used so far:
* '''AGOS''', '''SCI''', '''SCUMM''', whatever engine name
* '''AGOS''', '''SCI''', '''SCUMM''', whatever engine name
* '''SDL''', '''Android''', '''WII''', '''NDS''', whatever backend name
* '''SDL''', '''ANDROID''', '''WII''', '''NDS''', whatever backend name
* '''OSystem''': our middleware code
* '''OSYSTEM''': our middleware code
* '''i18n''': internationalization
* '''I18N''': internationalization
* '''GUI''': all gui-related
* '''GUI''': all gui-related
* '''TOOLS''': ScummVM tools module or built-in tools
* '''TOOLS''': ScummVM tools module or built-in tools
Line 42: Line 52:
After first line, an empty line is required which is used as separator. This first line has to be short and less than 50 characters so the log will fit on a standard 80-column terminal.
After first line, an empty line is required which is used as separator. This first line has to be short and less than 50 characters so the log will fit on a standard 80-column terminal.


== Good Practice ==
== Commit messages ==
Commit messages like the following aren't very helpful:
Commit messages like the following aren't very helpful:
* "not needed"  -> uhm, what is not needed?
* "not needed"  -> uhm, what is not needed?
Line 80: Line 90:
* Avoid committing style or whitespace fixes and functionality fixes in one go. It makes merging difficult, and also makes it harder to understand just what functional changes were made. In the case of documentation files, it can make the job of the translation teams more complicated, as it becomes difficult for them to determine exactly what content changes need to be translated.
* Avoid committing style or whitespace fixes and functionality fixes in one go. It makes merging difficult, and also makes it harder to understand just what functional changes were made. In the case of documentation files, it can make the job of the translation teams more complicated, as it becomes difficult for them to determine exactly what content changes need to be translated.
* Avoid committing changes to multiple files in one go with a generic, vague message. Instead, commit each file (or small, related groups of files) with tailored commit messages.
* Avoid committing changes to multiple files in one go with a generic, vague message. Instead, commit each file (or small, related groups of files) with tailored commit messages.
== Autoprops for subversion ==
Insert these in ~/.subversion/config
<syntax type="apache">
# Graphic file formats, usually binary:
*.bmp = svn:mime-type=image/bmp
*.gif = svn:mime-type=image/gif
*.ico = svn:mime-type=image/x-icon
*.jpeg = svn:mime-type=image/jpeg
*.jpg = svn:mime-type=image/jpeg
*.pdf = svn:mime-type=application/pdf
*.png = svn:mime-type=image/png
*.tiff = svn:mime-type=image/tiff
*.psd = svn:mime-type=image/x-photoshop
# Text / documentation files
*.rtf = svn:mime-type=text/rtf;svn:eol-style=native
*.tex = svn:mime-type=text/plain;svn:eol-style=native
README* = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
INSTALL = svn:mime-type=text/plain;svn:eol-style=native
COPY* = svn:mime-type=text/plain;svn:eol-style=native
HISTORY = svn:mime-type=text/plain;svn:eol-style=native
*.1 = svn:mime-type=text/plain;svn:eol-style=native
*.pc = svn:mime-type=text/plain;svn:eol-style=native
CHANGELOG = svn:mime-type=text/plain;svn:eol-style=native
FILEFORMAT = svn:mime-type=text/plain;svn:eol-style=native
THANKS = svn:mime-type=text/plain;svn:eol-style=native
luac = svn:mime-type=text/plain;svn:eol-style=native
# Project / build files
*.bat = svn:mime-type=text/plain;svn:eol-style=native
*.mak = svn:mime-type=text/plain;svn:eol-style=native
*.mk = svn:mime-type=text/plain;svn:eol-style=native
*.dsp = svn:mime-type=text/plain;svn:eol-style=CRLF
*.dsw = svn:mime-type=text/plain;svn:eol-style=CRLF
Makefile* = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
project.pbxproj = svn:mime-type=text/xml;svn:eol-style=native
# Source code (keyword expansion enabled by default)
*.c = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.cpp = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.css = svn:mime-type=text/css;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.gap = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.h = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.hpp = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.htm = svn:mime-type=text/html;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.html = svn:mime-type=text/html;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.m = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.mm = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.php = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.inc = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.csv = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.js = svn:mime-type=text/javascript;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.tpl = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.po = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.pot = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
POTFILES = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.sed = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
po2c = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id;svn:executable=1
*.bdf = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.vcproj = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.sln = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.bat = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
*.lua = svn:mime-type=text/plain;svn:eol-style=native;svn:keywords=Date Rev Author URL Id
# Various resource file formats
*.rc = svn:mime-type=text/plain;svn:eol-style=native
*.sh = svn:mime-type=text/plain;svn:eol-style=native;svn:executable
*.spec = svn:mime-type=text/plain;svn:eol-style=native
*.strings = svn:mime-type=text/plain;svn:eol-style=native
*.txt = svn:mime-type=text/plain;svn:eol-style=native
*.xhtml = svn:mime-type=application/xhtml+xml;svn:eol-style=native
*.xml = svn:mime-type=text/xml;svn:eol-style=native
*.xsl = svn:mime-type=text/xml;svn:eol-style=native
classes.nib = svn:mime-type=text/plain;svn:eol-style=native
info.nib = svn:mime-type=text/plain;svn:eol-style=native
objects.nib = svn:mime-type=application/octet-stream
keyedobjects.nib = svn:mime-type=application/octet-stream
*.fcc = svn:mime-type=application/octet-stream
</syntax>
81

edits

Navigation menu