Grzegorz Ferenc | bae3e7d | 2021-10-19 15:49:45 +0200 | [diff] [blame] | 1 | ## Matter Project Flow |
Rob Walker | f216ea0 | 2020-03-20 13:26:10 -0700 | [diff] [blame] | 2 | |
Grzegorz Ferenc | bae3e7d | 2021-10-19 15:49:45 +0200 | [diff] [blame] | 3 | This section is intended to cover how Matter uses GitHub Projects, Issues, |
Justin Wood | 0c46b2e | 2020-04-17 14:20:48 -0700 | [diff] [blame] | 4 | Milestones, Releases, and Branches for program/project management in the code |
| 5 | repository. |
Rob Walker | f216ea0 | 2020-03-20 13:26:10 -0700 | [diff] [blame] | 6 | |
| 7 | ### Issues |
| 8 | |
Grzegorz Ferenc | bae3e7d | 2021-10-19 15:49:45 +0200 | [diff] [blame] | 9 | Matter uses issues as simple problem descriptions or feature requests. In |
| 10 | general, 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 |
lzgrablic02 | a9f7b80 | 2021-12-16 03:24:03 -0500 | [diff] [blame] | 12 | in some cases duplicative, so consider these guidelines when deciding whether |
Grzegorz Ferenc | bae3e7d | 2021-10-19 15:49:45 +0200 | [diff] [blame] | 13 | you can get away with not creating an issue: |
Rob Walker | ef68279 | 2020-04-02 08:14:33 -0700 | [diff] [blame] | 14 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 15 | - 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 Walker | f216ea0 | 2020-03-20 13:26:10 -0700 | [diff] [blame] | 23 | |
| 24 | ### Pull requests |
| 25 | |
| 26 | Pull requests should be small and address a single, specific change to the code |
Justin Wood | 0c46b2e | 2020-04-17 14:20:48 -0700 | [diff] [blame] | 27 | base. They should be easy to review, as a "yes, that's better". Refrain from |
Rob Walker | f216ea0 | 2020-03-20 13:26:10 -0700 | [diff] [blame] | 28 | requesting review until all PR checks have completed successfully, lest you tire |
| 29 | your reviewers. |
| 30 | |
Rob Walker | ef68279 | 2020-04-02 08:14:33 -0700 | [diff] [blame] | 31 | PR Don'ts: |
Rob Walker | ef68279 | 2020-04-02 08:14:33 -0700 | [diff] [blame] | 32 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 33 | - 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 Walker | ef68279 | 2020-04-02 08:14:33 -0700 | [diff] [blame] | 38 | |
Rob Walker | f216ea0 | 2020-03-20 13:26:10 -0700 | [diff] [blame] | 39 | ### Milestones |
| 40 | |
Grzegorz Ferenc | bae3e7d | 2021-10-19 15:49:45 +0200 | [diff] [blame] | 41 | In Matter parlance, a milestone is simply a tag for an expected due date or |
Rob Walker | 52caf36 | 2020-04-21 11:04:56 -0700 | [diff] [blame] | 42 | release. Milestones are intended to help contributors and their managers to |
| 43 | prioritize work. There are 2 types: Date-based and Release-based. |
Rob Walker | f216ea0 | 2020-03-20 13:26:10 -0700 | [diff] [blame] | 44 | |
Rob Walker | 52caf36 | 2020-04-21 11:04:56 -0700 | [diff] [blame] | 45 | #### Date-based |
Justin Wood | 0c46b2e | 2020-04-17 14:20:48 -0700 | [diff] [blame] | 46 | |
Rob Walker | 52caf36 | 2020-04-21 11:04:56 -0700 | [diff] [blame] | 47 | Date-based milestones are named for their due date, typically a Friday of some |
| 48 | week. Date-based milestones are normally assigned based on a guess about when |
| 49 | something's likely to bubble up and get done based on current work load and |
| 50 | resourcing. They are wishes, guesses. |
Rob Walker | f216ea0 | 2020-03-20 13:26:10 -0700 | [diff] [blame] | 51 | |
Rob Walker | 52caf36 | 2020-04-21 11:04:56 -0700 | [diff] [blame] | 52 | #### Release-based |
| 53 | |
| 54 | Release-based milestones are named for the release version and may have flexible |
| 55 | or subject-to-change due dates. Release-based milestones are intended to track |
| 56 | release blockers. |
| 57 | |
| 58 | A special "Not sure when" milestone is a marker for issues whose priority, |
| 59 | scope, or blocking status have not been determined. Monthly review of these is a |
| 60 | project goal. |
| 61 | |
| 62 | Issues without milestones are those that have yet to be considered for one of |
| 63 | the above. Weekly review of new issues is a project goal. |
Rob Walker | f216ea0 | 2020-03-20 13:26:10 -0700 | [diff] [blame] | 64 | |
| 65 | ### Projects |
| 66 | |
| 67 | Projects are collections of issues, pull requests, and notes intended to capture |
| 68 | larger efforts that don't fit in issues, have multiple-subsystems involved, or |
Justin Wood | 0c46b2e | 2020-04-17 14:20:48 -0700 | [diff] [blame] | 69 | may span multiple milestones. We use projects 2 ways: |
Rob Walker | 4d43c0b | 2020-03-26 10:26:42 -0700 | [diff] [blame] | 70 | |
Justin Wood | 0c46b2e | 2020-04-17 14:20:48 -0700 | [diff] [blame] | 71 | 1. 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 Walker | ef68279 | 2020-04-02 08:14:33 -0700 | [diff] [blame] | 74 | 2. To categorize issues, denote broader efforts without a definite time scope. |
Justin Wood | 0c46b2e | 2020-04-17 14:20:48 -0700 | [diff] [blame] | 75 | These projects might reflect or show burndown or percent complete, but are |
| 76 | mostly used to view where effort is going. |
Rob Walker | 4d43c0b | 2020-03-26 10:26:42 -0700 | [diff] [blame] | 77 | |
Rob Walker | ef68279 | 2020-04-02 08:14:33 -0700 | [diff] [blame] | 78 | Issues can belong to any number of projects, but should generally only belong to |
Rob Walker | 4d43c0b | 2020-03-26 10:26:42 -0700 | [diff] [blame] | 79 | one of the task-tracking projects (the first type). |
Rob Walker | f216ea0 | 2020-03-20 13:26:10 -0700 | [diff] [blame] | 80 | |
| 81 | ### Branches, releases, and general development flow |
| 82 | |
Grzegorz Ferenc | bae3e7d | 2021-10-19 15:49:45 +0200 | [diff] [blame] | 83 | Master should always be Matter's best branch. Release branches, once cut, are |
Justin Wood | 0c46b2e | 2020-04-17 14:20:48 -0700 | [diff] [blame] | 84 | closed for any feature work. Software fixes for release branches must first land |
| 85 | on master unless demonstrably infeasible. |