Project

General

Profile

Development process » History » Version 17

Peter Amstutz, 07/18/2023 09:27 PM

1 1 Peter Amstutz
h1. Summary of Development Process
2
3
{{toc}}
4
5 8 Tom Clegg
h1. Issue descriptions
6
7
Consider starting with this outline (omitting empty/obvious sections):
8
* Background / context
9
* Current behavior
10
* Desired improvements
11
* Proposed implementation
12
* Exclusions / clarifications
13
* Open questions
14
15 1 Peter Amstutz
h1. Revision control
16
17
h2. Branches
18
19
* All development should be done in a branch.  The only exception to this should be trivial bug fixes.  What is trivial enough to not need review is the judgement of the developer, but when in doubt, ask for a review.
20
* Each story should be done in its own branch.
21
* Branch names are "####-story-summary" where #### is the redmine issue number followed by 3 or 4 words that summarize the story.
22
* Make your local branches track the main repository (@git push -u@)
23 9 Peter Amstutz
* Commit regularly, and push your branch to @git.arvados.org@ at the end of each day 
24
** Be paranoid, commits are cheap, pushing your commits to the remote repository is cheap, losing work is expensive
25 10 Peter Amstutz
** The preferred format of a commit message on a branch is like this (where 12345 should be replaced by the redmine issue number):
26
<pre>
27
12345: One line summary of changes in this commit
28
29
More detailed description of changes if relevant.
30
31
Arvados-DCO-1.1-Signed-off-by: Your Name <your.email@curii.com>
32
</pre>
33 1 Peter Amstutz
* Don't push uninvited changes to other developer's branches.
34
** To contribute to another developer's branch, check with them first, or create your own branch ("####-story-summary-ABC" where ABC are your initials) and ask the other developer to merge your branch.
35
36
h3. Merging
37
38 6 Ward Vandewege
Branches should not be merged to main until they are ready (see [[Summary of Development Process#Ready to merge|Ready to merge]] below).
39 1 Peter Amstutz
40
# @git remote -v@
41 6 Ward Vandewege
** Make sure your @origin@ is git.arvados.org, not github. *Don't push directly to the github main* branch -- let git.arvados.org decide whether it's OK to push to github.
42
# @git checkout main@
43 1 Peter Amstutz
# @git pull --ff-only@
44 6 Ward Vandewege
#* This ensures your main is up to date. Otherwise "git push" below might fail, and you'll be backtracking.
45 1 Peter Amstutz
# @git merge --no-ff branchname@
46
#* *The @--no-ff@ part is important!* It ensures there is actually a commit representing this merge. This is your opportunity to record the name of your branch being merged, and the relevant story number. Without it, the git history looks like we all just mysteriously started developing at the tip of your (now unnamed) feature branch.
47
#* In your merge commit message, *include the relevant story/issue number* (either "@refs #1234@" or "@closes #1234@").
48 4 Nico César
#* In your merge commit message, *include Arvados-DCO-1.1-Signed-off-by line* (i.e. Arvados-DCO-1.1-Signed-off-by: Jane Doe <jane@example.com>)
49 10 Peter Amstutz
#* The preferred format of a merge commit message is like this:
50
<pre>
51
Merge branch '12345-story-summary'
52
53
refs #12345
54
55
Arvados-DCO-1.1-Signed-off-by: Your Name <your.email@curii.com>
56
</pre>
57 1 Peter Amstutz
# @git push@
58 3 Peter Amstutz
# Look for Jenkins' build results at https://ci.arvados.org .
59 1 Peter Amstutz
60
h3. Rejected pushes
61
62 6 Ward Vandewege
We have a git hook in place that will reject pushes that do not follow these guidelines.  The goal of these policies is to ensure a clean linear history of changes to main with consistent cross referencing with issue numbers.  These policies apply to the commits listed on "git rev-list --first-parent" when pushing to main, and not to commits on any other branches.
63 1 Peter Amstutz
64
If you try to push a (set of) commit(s) that does not pass mustard, you will get a [POLICY] reject message on stdout, which will also list the offending commit. You can use
65
66
  git commit --amend
67
68
to update the commit message on your last commit, if that is the offending one, or else you can use 
69
70
  git rebase --interactive
71
72
to rebase and fix up a commit message on an earlier commit.
73 6 Ward Vandewege
74 1 Peter Amstutz
h4. All merge commits to main must be from a feature branch into main
75 6 Ward Vandewege
76 1 Peter Amstutz
Merges that go the other way (from main to a feature branch) that get pushed to main as a result of a fast-forward push will be rejected.  In other words:  when merging to main, make sure to use --no-ff.
77 6 Ward Vandewege
78 1 Peter Amstutz
h4. Merges between local and remote main branches will be rejected
79 6 Ward Vandewege
80 1 Peter Amstutz
Merges between local and remote main branches (generally merges created by "git pull") will be rejected, in order to maintain a linear main history.  If this happens, you'll need to reset main to the remote head and then remerge or rebase.
81
82
h4. Proper merge message format
83 6 Ward Vandewege
84 1 Peter Amstutz
All merge commits to main must include the text "Merge branch 'featurebranch'" or they will be rejected.
85
86 10 Peter Amstutz
h4. All commits to main include an issue number or explicitly say "no issue #"
87 1 Peter Amstutz
88 6 Ward Vandewege
All commits to main (both merges and single parent commits) must
89 11 Peter Amstutz
include the text "refs #", "closes #", "fixes #", or "no issue #" or they will be
90 1 Peter Amstutz
rejected.
91
92
h4. Avoid broken commit messages
93
94
Your commit message matches
95
96
  /Please enter a commit message to explain why this merge is necessary/
97
98
h2. Commit logs
99
100 5 Ward Vandewege
See https://dev.arvados.org/projects/arvados/wiki/Coding_Standards
101 1 Peter Amstutz
102
h2. Code review process
103
104
Code review has high priority! Branches shouldn't sit around for days waiting for review/merge.
105
106
When your branch is ready for review:
107
# Create/update a review task on the story so it looks like this:
108
#* subject = "review {branch name}"
109
#* state = in progress
110
#* assignee is not null
111 12 Tom Clegg
# Comment on the issue page (not the review page), including
112
#* branch name
113
#* commit hash
114
#* link to Jenkins test run
115
#* if appropriate, a brief description of what's in the branch (may be omitted if it's already in the commit messages, or if it would just be a copy of the issue subject/description)
116 1 Peter Amstutz
# Ping your reviewer (during daily standup, via e-mail and/or via chat).
117
118
Doing a review:
119 13 Peter Amstutz
# Reviewers are usually assigned at sprint kickoff, but if you don't have a reviewer, ask for a volunteer in chat and/or at daily stand-up.
120 1 Peter Amstutz
# When you start the review, assign the review task to yourself and move the review task to "in progress" to make sure other people don't duplicate your effort.
121 6 Ward Vandewege
# The recommended process for reviewing diffs for a branch is @git diff main...branchname@.  The reviewer must make sure that their repository is up to date (or use @git diff origin/main...origin/branchname@). Note the 3 dots (not two)
122 16 Peter Amstutz
# The reviewer goes through the [[#Ready-to-merge]] checklist
123 14 Peter Amstutz
# After doing a review, write up comments ("fix these problems" or "ready to merge") to the story page, make a note of the git commit revision that was reviewed, assign the review task back to the original developer, and notify the original developer by chat (or by some other means such as at daily standup).
124
#* In comments, it is helpful to indicate how strongly you feel how/important the comment is as "low", "medium", or "high"
125 7 Tom Clegg
#* low: nitpick not necessarily worth changing here if you don't feel like it, but I'm mentioning it to help improve habits
126
#* medium: suggestion/idea that you should at least acknowledge/respond to, even if we don't end up resolving it here
127 1 Peter Amstutz
#* high: we should make sure we both agree on how this is resolved before merging
128 7 Tom Clegg
# The original developer should address any outstanding problems/comments in the code, then write a brief response indicating which points were dealt with or intentionally rejected/not addressed.
129 14 Peter Amstutz
# If the response involves more commits, do that, then goto "branch is ready for review". This process iterates until the branch is deemed ready to merge (indicating by posting a comment with "LGTM" for "Looks Good To Merge")
130
# When the comments are all low priority, someone might write something like "LGTM if you fix this one typo", this indicates that once the minor comments are handled (fixed or responded to) that the branch should be merged without another review cycle.
131 1 Peter Amstutz
# Once the branch is merged, move the "review" task to "resolved".
132
133
To list unmerged branches:
134 6 Ward Vandewege
* Yours: @git branch --no-merged main@
135
* Everyone: @git branch -a --no-merged main@
136 1 Peter Amstutz
137
h2. Ready to merge
138
139
When merging, both the developer and the reviewer should be convinced that:
140 6 Ward Vandewege
* Current/recent main is merged. (Otherwise, you can't predict what merge will do.)
141 1 Peter Amstutz
* The branch is pushed to git.arvados.org
142
* The code is suitably robust.
143
* The code is suitably readable.
144
* The code is suitably scalable. For example, client code is not allowed to print or sort unbounded lists. If the code handles a list of items, consider what happens when the list is 10x as large as you expect. What about 100x? A million times?
145
* The code accomplishes what the story specified. If not, explain why (e.g., the branch is only part of the story, a better solution was found, etc.) in the issue comments
146
* New API names (methods, attributes, error codes) and behaviors are well chosen. It sucks to change them later, and have to choose between compatibility and greatness.
147
* Tests that used to pass still pass. (Be extremely careful when altering old tests to make them pass. Do not change existing tests to test new code. Add assertions and write new tests. If you change or remove an existing test, you are breaking behavior that someone already decided was worth testing!)
148
* Recent clients/SDKs work against the new API server. (Things rarely turn out well when we rely on all clients being updated at once in lockstep with the API server. Our test suite doesn't check this for us yet, so for now we have to pay attention.)
149
* New/fixed behavior is tested. (Although sometimes we decide not to block on inadequate testing infrastructure... that sucks!)
150
* New/changed behavior is documented. Search the doc site for relevant keywords to help you find the right sections.
151
* Whitespace errors are not committed. (Tab characters, spaces at EOL, etc.)
152
* Git commit messages are descriptive (see [[arvados:Coding Standards]]). If they aren't, this is your last chance to rebase/reword.
153 17 Peter Amstutz
* For GUI work: user interface elements meet [[arvados:Coding Standards]]
154 1 Peter Amstutz
155
h2. Handling pull requests from github
156
157
_This is only for contributions by *external contributors*, i.e., people who don't have permission to write directly to arvados.org repositories._
158
159 6 Ward Vandewege
First make sure your main is up to date.
160 1 Peter Amstutz
161 6 Ward Vandewege
    git checkout main; git pull --ff-only
162 1 Peter Amstutz
163
*Option 1:* On the pull request page on github, click the "You can also merge branches on the command line" link to get instructions.
164
165
* Don't forget to run tests.
166
167
*Option 2:* (a bit shorter)
168
169 6 Ward Vandewege
Say we have "chapmanb  wants to merge 1 commit into arvados:main from chapmanb:branchname"
170 1 Peter Amstutz
* @git fetch https://github.com/chapmanb/arvados.git branchname:chapmanb-branchname@
171
* @git merge --no-ff chapmanb-branchname@
172
* Use the commit message: @Merge branch 'branchname' from github.com/chapmanb. No issue #@
173
(or @refs #1234@ if there is an issue#)
174 6 Ward Vandewege
* Confirm diff: @git diff origin/main main@
175 1 Peter Amstutz
* Run tests
176
* @git push@
177
178
h1. Non-fast-forward push
179
180
Please don't get into a situation where this is needed.
181
182 6 Ward Vandewege
# On dev box: @git push -f git@github.com:arvados/arvados proper_head_commit:main proper_head_commit:staging@
183
# On dev box: @git push -f git@git.arvados.org:arvados.git proper_head_commit:main@
184
# As gitsync@dev.arvados.org: @cd /scm/arvados; git fetch origin; git checkout main; git reset --hard origin/main@
185 1 Peter Amstutz
186
(At least that's what TC did on 2016-03-10. We'll see how it goes.)
187
188
h1. Working with external upstream projects
189
190
Development process summary (1-6 should follow the guidelines above)
191
192
# Each feature is developed in a git branch named @<issue_number>-<summary>@, for example @12521-web-app-config@
193
# Each feature has a "Review" task.  You can see the features and review tasks on the task board.
194
# When the feature branch is ready for review, update the title of the Review task to say "Review <branchname>" and move it from the *New* column the to *In Progress* column
195
# The reviewer responds on the issue page with questions or comments
196
# When the branch is ready to merge, the reviewer will add a comment "Looks Good To Me" (LGTM) on the issue page
197
# Merge the feature into into the Arvados main branch
198
# Push the feature branch to github and make a pull request (PR) of the branch against the external project upstream
199
# Handle code review comments/change requests from the external project team
200 6 Ward Vandewege
# Once the external project merges the PR, merge external project upstream main back into the feature branch
201 1 Peter Amstutz
# Determine if external project upstream brings any unrelated changes that breaks things for us
202
# If necessary, make fixes, make a new PR, repeat until stable
203 6 Ward Vandewege
# Merge the feature branch (now up-to-date with external project upstream) into Arvados main
204 1 Peter Amstutz
205
This process is intended to let us work independently of how quickly the external project team merges our PRs, while still maximizing the chance that they will be able to accept our PRs by limiting the scope to one feature at a time.
206
207 6 Ward Vandewege
This assumes using git merge commits and avoiding rebases, so we can easily perform merges back and forth between the three branches (Arvados main, feature, external project main).
208 1 Peter Amstutz
209
210
h1. Scrum
211
212
h2. References
213
214
These books give us a reference point and vocabulary. 
215
216
* _Essential Scrum: A Practical Guide to the Most Popular Agile Process_ by Kenneth Rubin
217
* _User Stories Applied: For Agile Software Development_ by Mike Cohen
218
219
h2. Roles
220
221
222
h3. Product Owner
223
224
* Decide what goes on the backlog
225
* Decide backlog priorities
226
* Work with stakeholders to understand their requirements and priorities
227
* Encode stakeholder requirements/expectations as user stories
228
* Lead sprint planning meetings 
229
* Lead release planning meetings 
230
* Lead product planning meetings 
231
* Lead Sprint Kick-off Meetings
232
* Lead Sprint Review Meetings
233
* Decide on overall release schedule 
234
235
h3. Scrum Master
236
237
* Lead Daily Scrum Meeting
238
* Help to eliminate road blocks 
239
* Lead Sprint Retrospective Meetings
240
* Organize Sprint Schedule 
241
* Help team organize and stay on track with Scrum process
242
* Teach new engineers how Scrum works
243
244
h3. Top stakeholders
245
246
* Conduct market research 
247
* Synthesize market research into user stories 
248
* Work with Product Owner to prioritize stories
249
* Define overall business goals for product 
250
* Work with Product Owner to define overall release cycle 
251
* Organize User Input and dialog with users for engineering team 
252
* Contribute to backlog grooming 
253
* Bring voice of customer into planning process 
254
* Define user personas 
255
* Coordinate user communication 
256
* Develop technical marketing and sales materials 
257
* Assist sales team in presenting product value proposition
258
* Train sales in technical aspects of the product
259
260
h2. Definition of Done
261
262
An issue is resolved when:
263
264
* Code is written
265
* Existing code is refactored if appropriate
266
* Documentation is written/updated
267
* Acceptance tests are satisfied
268 6 Ward Vandewege
* Code is merged in main
269 1 Peter Amstutz
* All Jenkins jobs pass (test, build packages, deploy to dev clusters)
270
* Feature works on applicable dev clusters
271
272
h2. Standard Schedule
273
274
Sprints are two weeks long. They start and end on Wednesdays.
275
276
h3. Key meetings
277
278 2 Peter Amstutz
Every day:
279 1 Peter Amstutz
280
Daily Scrum (15 Minutes)
281
Who: Development team, product owner. Silent observers welcome.
282
* What did you do yesterday?
283
* What will you do today?
284
* What obstacles are in your way?
285
286
h4. Sprint review & kickoff (every 2 weeks on Wednesday):
287
288
Sprint Review (30 minutes)
289
Who: Development team, product owner, stakeholders.
290
* Demo of each feature built and relationship to stories
291
* Product owner explains which backlog items are done
292
* Development team demonstrates the work done, and answers questions about the sprint increment
293
* Product owner discusses the backlog as it stands. Revise expected completion dates based on recent progress (if needed)
294
* Review current product status in context of business goals
295
296
Sprint Retrospective (30 minutes)
297
Who: Development team, product owner.
298
* Review what processes worked well, and what didn't, in the sprint just finished
299
* Propose and agree to changes to improve future sprints
300
* Assign action items (meetings/tasks) to implement agreed-upon process improvements
301
302
Sprint Kick Off (1 hour)
303
Who: Development team, product owner.
304
* Add latest bugs or dependencies to sprint
305
* Create tasks for each story
306
* Assign a developer to each task
307
* Assign an on-call engineer for that sprint who will triage customer support requests
308
* Check that commitment level is realistic
309
310
h4. Planning (alternate Wednesdays mid-sprint)
311
312 2 Peter Amstutz
Roadmap review (1 hour)
313 1 Peter Amstutz
Who: Development team, product owner, stakeholders.
314 2 Peter Amstutz
* Report high level status of epics
315
* Prioritize epics
316
* Define new epics
317 1 Peter Amstutz
318 2 Peter Amstutz
Sprint Planning (1-2 hours)
319 1 Peter Amstutz
Who: Development team, product owner.
320 2 Peter Amstutz
* Discuss and get engineering team consensus on feature design & implementation strategy for tasks on current and upcoming epics