Repository navigation
Expand file tree
/
Copy pathProjectGuide
More file actions
152 lines (118 loc) · 7.5 KB
/
Copy pathProjectGuide
File metadata and controls
152 lines (118 loc) · 7.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
$Id: ProjectGuide,v 1.3 2010/06/14 20:08:58 cm-msk Exp $
OpenDKIM Release Planning
MAJOR RELEASES: Major releases (i.e. for version x.y.z, those for which
"x" increases) contain major new features or major code rewriting efforts.
With very few exceptions, they are typically planned several months apart
to allow for development complexity and extensive unit testing. They may
be planned in conjunction with releases with other projects where the two
are co-operating in some way. They should also include a beta period of
at least a month. Heavy code review activity is expected. Users should
anticipate the possibility of breakage if a binary replacement is done;
though this will be avoided whenever practical, these releases are the
ones where backward compatibility is most likely to be broken. Any change
that establishes a new external dependency must occur in a major release.
MINOR RELEASES: Minor releases (those for which "y" increases) contain new
features or code changes not warranting a full major release. They are also
typically planned a few months apart, though with more frequency than
major releases. They generally coincide with conferences or other public
events where the code or related topics may be featured, but this is not
a scheduling requirement. They should always include a beta period of at
least two weeks but preferably a month. Code review is required; anything
not reviewed by release should be demoted to an FFR. An existing FFR can be
activated, or a new one added, in a minor release. Backward compatibility
with existing versions should be maintained whenever possible. No new
external dependencies may be created.
PATCH RELEASES: Patch releases (those for which only "z" increases) contain
fixes to existing code only, and never contain new features or remove existing
ones. A patch release is typically scheduled for two weeks after an important
bug is reported, and any other bugs that occur during that window are generally
included in that release. However, a patch release is never scheduled when
doing so would collide with some other pending release. Beta periods are
generally not required, though developers should plan to add unit tests to
fixes where possible. Backward compatibility must be preserved in patch
releases except where doing so is simply impossible.
NOTES:
- changes to anything in the "contrib" directory may appear in any release as
they are unsupported
OpenDKIM Source Code Management Policies
1) Anything major (all new features, all new dependencies, any large
rewrites or changes to algorithms, all package rearrangements, etc.) should
get reviewed before going onto the trunk, and must get reviewed and run in
the real world for a while before it gets released. You can post the
proposed diffs, or just describe the work you're doing, on the opendkim-dev
list before actually starting commits.
2) Simple bug fixes to existing code can go in without being reviewed, but
review is still encouraged. All developers are encouraged to keep an eye
on what's going through the opendkim-cvs list for possible mistakes or other
spontaneous review.
3) If you have questions about someone's design or choice of how to fix
something, and especially if you have an idea about a more solid approach,
feel free to bring it up on opendkim-dev. We're a community of experienced
people, so peer review is important and encouraged.
4) Nothing, even small things, should go in to any release branch or the
trunk without being build-tested and run someplace first.
5) When making changes or improvements to libopendkim, write a unit test and
add it to the system to cover your work. You can copy one of the existing
ones and modify it accordingly. Any changes to libopendkim have to leave it
with all unit tests still running.
6) Stick to the coding style (braces, tabs, comments, etc.). The code
should look like it came from a coherent team; I shouldn't be able to tell
where you patched something I wrote without using "cvs annotate".
7) Anything you change should be documented in the RELEASE_NOTES file,
following its current format. You don't need to document fixed typos or
truly trivial things of that nature, but just about everything else should
be mentioned. Remember to give credit where credit is due, though we
generally don't attribute credit to people who are part of the project
itself unless it's really a major contribution.
8) If you want a development sandbox, create a branch first (see below)
and do your experimenting there. Commits to sandbox branches don't need
to be reviewed by anyone. Sandboxes only get merged to release branches or
the trunk after passing a review.
9) CVS commits on non-sandbox branches should describe what changed in enough
detail to indicate to one of us why the change was made. We can see what
changed using "cvs diff", so the "why" is important here. If you had
any review done of your work, name the person(s) that did the review in
your commit comment.
10) Nothing should cause compile-time warnings unless there's a really good
reason not to clean them up. If that's the case, explain why the warnings
should be tolerated in your commit comment.
11) Start your commit comment with "MFC:" (move from current) if the diff is
a copy from the trunk, or with "MFB:" (move from branch) if it's a copy to
the trunk, and name the other branch involved.
12) Where a commit references an open bug or feature request, specify such
(e.g. "Fix bug #SF1234567" or "Feature request #SF2345678") as well as some
descriptive text such as the problem being solved or the feature being
added. The "SF" prefix is legacy from the times when there was more
than one bug tracking system in use, but let's stick with it for now.
Sandbox branching procedure:
1) Update your code to the point in CVS at which you want to branch
2) update the BRANCHES file to contain your branch
3) Check in the BRANCHES file "cvs commit -m 'add branch XXX'"
4) "cvs tag base-<yourname>-<branchname>" (e.g. "cvs tag base-dblack-async-dns")
to lay down a reference tag, so that later you can produce a final diff of
your work relative to the branch point
5) "cvs tag -b br-<yourname>-<branchname>" to create the branch
6) Update your copy so it refers to the branch
(e.g. "cvs update -r br-<yourname>-<branchname>").
7) Code away!
Production branch notes:
1) All branches should belong to a person (i.e. be named, like "br-msk-...")
unless they are release branches, in which case they are named after that code
fork (e.g. "br-1-1" is for 1.1.x releases). No branches or tags should ever
be deleted.
2) Whoever's doing releases (currently only msk) is responsible for all
non-sandbox branch creation, and is also responsible for placing release
tags during releases.
3) New features and dependencies only ever go on the trunk, never on release
branches. The exception to this is FFRs; new FFRs can go in on any branch
since they are off-by-default anyway, but still this should be avoided. FFRs
only ever "go live", becoming production code, on the trunk.
4) Bug fixes relative to code that has already been released go on both the
current release branch and the trunk.
5) When it's time for a new release line to begin (e.g. 1.1.x has been
created but it's time to get some new features out so we need to start
the 1.2.x releases), start a new release branch and do releases from there.
(A new release line can run concurrently with the trunk until new features
start to go in, at which point a release branch is required.)
If anyone has questions about anything above, feel free to ask about them
before doing something that could cause a mess.