blob: d8579a4e962154d161b43567ab10af5b0a37bc3d [file] [log] [blame] [view]
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +02001## Matter Project Flow
Rob Walkerf216ea02020-03-20 13:26:10 -07002
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +02003This section is intended to cover how Matter uses GitHub Projects, Issues,
Justin Wood0c46b2e2020-04-17 14:20:48 -07004Milestones, Releases, and Branches for program/project management in the code
5repository.
Rob Walkerf216ea02020-03-20 13:26:10 -07006
7### Issues
8
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +02009Matter uses issues as simple problem descriptions or feature requests. In
10general, all work contributed to the repository in the form of pull requests
11(PR) should be under the auspices of some open issue. This may seem onerous and
lzgrablic02a9f7b802021-12-16 03:24:03 -050012in some cases duplicative, so consider these guidelines when deciding whether
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +020013you can get away with not creating an issue:
Rob Walkeref682792020-04-02 08:14:33 -070014
Justin Wood0a9545e2020-04-20 18:15:21 -070015- Trivial fixes: issues can function as TODO lists, simple reminders that
16 something should be addressed. Sometimes, though, the work required to fix
17 is smaller than the work required to write the issue.
18- Issues intended to be addressed by a PR may not actually be fixed or may
19 regress.
20- Issues can span PRs (as PRs should be as small as possible, but no smaller).
21- Issues help form an important basis for release notes. Any PR that addresses
22 a problem that should have release visibility, please do open an issue.
Rob Walkerf216ea02020-03-20 13:26:10 -070023
24### Pull requests
25
26Pull requests should be small and address a single, specific change to the code
Justin Wood0c46b2e2020-04-17 14:20:48 -070027base. They should be easy to review, as a "yes, that's better". Refrain from
Rob Walkerf216ea02020-03-20 13:26:10 -070028requesting review until all PR checks have completed successfully, lest you tire
29your reviewers.
30
Rob Walkeref682792020-04-02 08:14:33 -070031PR Don'ts:
Rob Walkeref682792020-04-02 08:14:33 -070032
Justin Wood0a9545e2020-04-20 18:15:21 -070033- Don't combine unrelated changes. E.g. if the PR addresses a bug in some C
34 code, an update to the top-level .gitignore doesn't belong.
35- Don't make stacks. E.g. if a change in a component requires a new feature or
36 even a small tweak in one or more of its dependencies, each dependency
37 change belongs in its own separate PR.
Rob Walkeref682792020-04-02 08:14:33 -070038
Rob Walkerf216ea02020-03-20 13:26:10 -070039### Milestones
40
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +020041In Matter parlance, a milestone is simply a tag for an expected due date or
Rob Walker52caf362020-04-21 11:04:56 -070042release. Milestones are intended to help contributors and their managers to
43prioritize work. There are 2 types: Date-based and Release-based.
Rob Walkerf216ea02020-03-20 13:26:10 -070044
Rob Walker52caf362020-04-21 11:04:56 -070045#### Date-based
Justin Wood0c46b2e2020-04-17 14:20:48 -070046
Rob Walker52caf362020-04-21 11:04:56 -070047Date-based milestones are named for their due date, typically a Friday of some
48week. Date-based milestones are normally assigned based on a guess about when
49something's likely to bubble up and get done based on current work load and
50resourcing. They are wishes, guesses.
Rob Walkerf216ea02020-03-20 13:26:10 -070051
Rob Walker52caf362020-04-21 11:04:56 -070052#### Release-based
53
54Release-based milestones are named for the release version and may have flexible
55or subject-to-change due dates. Release-based milestones are intended to track
56release blockers.
57
58A special "Not sure when" milestone is a marker for issues whose priority,
59scope, or blocking status have not been determined. Monthly review of these is a
60project goal.
61
62Issues without milestones are those that have yet to be considered for one of
63the above. Weekly review of new issues is a project goal.
Rob Walkerf216ea02020-03-20 13:26:10 -070064
65### Projects
66
67Projects are collections of issues, pull requests, and notes intended to capture
68larger efforts that don't fit in issues, have multiple-subsystems involved, or
Justin Wood0c46b2e2020-04-17 14:20:48 -070069may span multiple milestones. We use projects 2 ways:
Rob Walker4d43c0b2020-03-26 10:26:42 -070070
Justin Wood0c46b2e2020-04-17 14:20:48 -0700711. To track burn down on a larger task. When constructing such a project, it's
72 important to think in terms of something that will eventually have an end,
73 i.e. a definite scope.
Rob Walkeref682792020-04-02 08:14:33 -0700742. To categorize issues, denote broader efforts without a definite time scope.
Justin Wood0c46b2e2020-04-17 14:20:48 -070075 These projects might reflect or show burndown or percent complete, but are
76 mostly used to view where effort is going.
Rob Walker4d43c0b2020-03-26 10:26:42 -070077
Rob Walkeref682792020-04-02 08:14:33 -070078Issues can belong to any number of projects, but should generally only belong to
Rob Walker4d43c0b2020-03-26 10:26:42 -070079one of the task-tracking projects (the first type).
Rob Walkerf216ea02020-03-20 13:26:10 -070080
81### Branches, releases, and general development flow
82
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +020083Master should always be Matter's best branch. Release branches, once cut, are
Justin Wood0c46b2e2020-04-17 14:20:48 -070084closed for any feature work. Software fixes for release branches must first land
85on master unless demonstrably infeasible.