| ## CHIP Project Flow |
| |
| This section is intended to cover how CHIP uses GitHub Projects, Issues, |
| Milestones, Releases, and Branches for program/project management in the code |
| repository. |
| |
| ### Issues |
| |
| CHIP uses issues as simple problem descriptions or feature requests. In general, |
| all work contributed to the repository in the form of pull requests (PR) should |
| be under the auspices of some open issue. This may seem onerous and in some |
| cases duplicative, so consider these guidelines when deciding whether to you can |
| get away with not creating an issue: |
| |
| - Trivial fixes: issues can function as TODO lists, simple reminders that |
| something should be addressed. Sometimes, though, the work required to fix |
| is smaller than the work required to write the issue. |
| - Issues intended to be addressed by a PR may not actually be fixed or may |
| regress. |
| - Issues can span PRs (as PRs should be as small as possible, but no smaller). |
| - Issues help form an important basis for release notes. Any PR that addresses |
| a problem that should have release visibility, please do open an issue. |
| |
| ### Pull requests |
| |
| Pull requests should be small and address a single, specific change to the code |
| base. They should be easy to review, as a "yes, that's better". Refrain from |
| requesting review until all PR checks have completed successfully, lest you tire |
| your reviewers. |
| |
| PR Don'ts: |
| |
| - Don't combine unrelated changes. E.g. if the PR addresses a bug in some C |
| code, an update to the top-level .gitignore doesn't belong. |
| - Don't make stacks. E.g. if a change in a component requires a new feature or |
| even a small tweak in one or more of its dependencies, each dependency |
| change belongs in its own separate PR. |
| |
| ### Milestones |
| |
| In CHIP parlance, a milestone is simply a tag for an expected due date or |
| release. Milestones are intended to help contributors and their managers to |
| prioritize work. There are 2 types: Date-based and Release-based. |
| |
| #### Date-based |
| |
| Date-based milestones are named for their due date, typically a Friday of some |
| week. Date-based milestones are normally assigned based on a guess about when |
| something's likely to bubble up and get done based on current work load and |
| resourcing. They are wishes, guesses. |
| |
| #### Release-based |
| |
| Release-based milestones are named for the release version and may have flexible |
| or subject-to-change due dates. Release-based milestones are intended to track |
| release blockers. |
| |
| A special "Not sure when" milestone is a marker for issues whose priority, |
| scope, or blocking status have not been determined. Monthly review of these is a |
| project goal. |
| |
| Issues without milestones are those that have yet to be considered for one of |
| the above. Weekly review of new issues is a project goal. |
| |
| ### Projects |
| |
| Projects are collections of issues, pull requests, and notes intended to capture |
| larger efforts that don't fit in issues, have multiple-subsystems involved, or |
| may span multiple milestones. We use projects 2 ways: |
| |
| 1. To track burn down on a larger task. When constructing such a project, it's |
| important to think in terms of something that will eventually have an end, |
| i.e. a definite scope. |
| 2. To categorize issues, denote broader efforts without a definite time scope. |
| These projects might reflect or show burndown or percent complete, but are |
| mostly used to view where effort is going. |
| |
| Issues can belong to any number of projects, but should generally only belong to |
| one of the task-tracking projects (the first type). |
| |
| ### Branches, releases, and general development flow |
| |
| Master should always be CHIPs best branch. Release branches, once cut, are |
| closed for any feature work. Software fixes for release branches must first land |
| on master unless demonstrably infeasible. |