1 |
|
2 |
CVS checkin process: |
3 |
|
4 |
1) All checkins should include a log message. Included in the log |
5 |
message should be what changed (files), why it changed (what new |
6 |
feature or bug was fixed), as well as the date and time (while CVS |
7 |
does stamp these automatically, it can be easier to read the log for |
8 |
that information than looking at the CVS header). |
9 |
|
10 |
It is not necessary to go into a long exposition, and pasting the actual |
11 |
changes is not generally useful. But this log message should be useful for |
12 |
someone looking over the logs at a future point to see what did change. |
13 |
Having a log like 'various skill stuff' isn't very useful. A log message like |
14 |
'prevent abuse with the literacy skill, and increase chance of singing' is |
15 |
much more useful, and not a lot more words. |
16 |
|
17 |
One of the main uses of the log entries is when bugs are reported where |
18 |
behaviour changed between version X and Y to be able to look at the log |
19 |
entries and get an idea of what specific revision may have caused that |
20 |
change. |
21 |
|
22 |
If doing a commit of several different files at each time, and the commits |
23 |
are different in nature, do try to at least mention what is changing in |
24 |
each file. |
25 |
|
26 |
Do not refer to other files or other log messages. Saying 'see changes |
27 |
file' is not useful, nor is a message like 'continuing with last set |
28 |
of commits'. Such messages are not useful when trying to look back through |
29 |
the logs at a future point. |
30 |
|
31 |
There is no excuse for not having a good log entry. Worst case, cut and |
32 |
past from the CHANGES file or those prior commits. My typical method |
33 |
of doing commits is filling out the CHANGES file, and then |
34 |
copying/pasting from that when I do the commit. |
35 |
|
36 |
Please also update the CHANGES file for the appropriate distribution - |
37 |
this is very useful to look through to get an idea of everything that |
38 |
has changed since some release. Very minor things (eg, fixing typos, |
39 |
or other things that don't actually effect how the program runs) do not |
40 |
need to be in the CHANGES file. |
41 |
|
42 |
2) All checkins should go through at least minimum testing: |
43 |
For source code, this means it compiles and at least a basic test has |
44 |
been done (for example, if it is a new spell, have you tried casting |
45 |
the spell?) This basic testing implies the code at least compiles |
46 |
also. I realize it is very difficult to do 100% testing of code, but |
47 |
at least a basic test should be done. |
48 |
|
49 |
All source code should also be ANSI & POSIX compliant. Don't use // for |
50 |
comments. Be careful of new library calls that are not being used |
51 |
elsewhere in the source - there may be a reason they are not being used. |
52 |
"it compiles on my system" is not justification for writing code that does |
53 |
not work elsewhere. It is understandable that you may not know that the |
54 |
code written is non portable, but once this is learned, it should be |
55 |
corrected. |
56 |
|
57 |
For archetypes, this testing should involve rebuilding the arch file and |
58 |
running with the new file. There should be no errors in the loading |
59 |
of the archetype files. |
60 |
|
61 |
For maps, this means that the map should load, and the exits should lead |
62 |
back and forth. Note that maps in the unlinked directory are more |
63 |
work in progress so can be checked in a more experimental state. |
64 |
|
65 |
3) Style & Balance: Your changes may work, but do they fit in with the |
66 |
rest of the game. This basically means following the files guides |
67 |
that already existing, eg doc/programming_guide, doc/mapguide |
68 |
|
69 |
There really is no arch guide, but take common sense. Does the |
70 |
object fit in with the game (ie, a blaster rifle would not), is this |
71 |
arch very unbalancing, etc. |
72 |
|
73 |
4) Before starting a big project, send a note to the mailing list asking |
74 |
for opinions. While it is not possible to prevent someone working on |
75 |
whatever they may want, if the general consensus is that it is a bad idea, |
76 |
you may want to find that out before spending a lot of work on it only |
77 |
to find out that your idea will not get added to the game. |
78 |
|
79 |
5) Take responsibility for your code. If you check in something and a bug |
80 |
is reported in it, go an fix it. |
81 |
|
82 |
6) Look at the testplans, and if your code may benefit from them, use them. |
83 |
Likewise, if you develope a testplan for your code, record it in the |
84 |
testplan directory. |
85 |
|
86 |
Mark Wedel |
87 |
May 12, 2001 |