docs/PROJECT_FLOW.md

## Matter Project Flow

This section is intended to cover how Matter uses GitHub Projects, Issues,
Milestones, Releases, and Branches for program/project management in the code
repository.

### Issues

Matter 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
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 Matter 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 Matter's 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.