docs/PROJECT_FLOW.md

   1 ## CHIP Project Flow
   2
   3 This section is intended to cover how CHIP uses GitHub Projects, Issues,
   4 Milestones, Releases, and Branches for program/project management in the code
   5 repository.
   6
   7 ### Issues
   8
   9 CHIP uses issues as simple problem descriptions or feature requests. In general,
  10 all work contributed to the repository in the form of pull requests (PR) should
  11 be under the auspices of some open issue. This may seem onerous and in some
  12 cases duplicative, so consider these guidelines when deciding whether to you can
  13 get away with not creating an issue:
  14
  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.
  23
  24 ### Pull requests
  25
  26 Pull requests should be small and address a single, specific change to the code
  27 base. They should be easy to review, as a "yes, that's better". Refrain from
  28 requesting review until all PR checks have completed successfully, lest you tire
  29 your reviewers.
  30
  31 PR Don'ts:
  32
  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.
  38
  39 ### Milestones
  40
  41 In CHIP parlance, a milestone is simply a tag for an expected due date or
  42 release. Milestones are intended to help contributors and their managers to
  43 prioritize work. There are 2 types: Date-based and Release-based.
  44
  45 #### Date-based
  46
  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.
  51
  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.
  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
  69 may span multiple milestones. We use projects 2 ways:
  70
  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.
  74 2. To categorize issues, denote broader efforts without a definite time scope.
  75    These projects might reflect or show burndown or percent complete, but are
  76    mostly used to view where effort is going.
  77
  78 Issues can belong to any number of projects, but should generally only belong to
  79 one of the task-tracking projects (the first type).
  80
  81 ### Branches, releases, and general development flow
  82
  83 Master should always be CHIPs best branch. Release branches, once cut, are
  84 closed for any feature work. Software fixes for release branches must first land
  85 on master unless demonstrably infeasible.