README.fuchsia

Name: Ninja
URL: https://ninja-build.org
Gerrit Git: https://fuchsia.googlesource.com/third_party/github.com/ninja-build/ninja
Upstream Git: https://github.com/ninja-build/ninja
Fuchsia RFC: https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0153_ninja_customization?hl=en
License: Apache 2.0
License File: COPYING
Fuchsia Bug: https://fxbug.dev/91545
Description:

Ninja is a small build system with a focus on speed. As explained in the
Fuchsia RFC-0153 document, this is a temporary custom branch of the upstream
Ninja sources to provide various improvements for the Fuchsia build. All
changes should be expressed as a set of small commits on top of the upstream
main branch, periodically rebased according to the strategy described in the
RFC document. Due to this, local modifications are not listed explictly here
to reduce unnecessary merge conflicts in this file.

Note that:

- Development happens in the `fuchsia-rfc-0153` branch of
  `https://fuchsia.googlesource.com/third_party/github.com/ninja-build/ninja`

- All patches need to be uploaded to Gerrit for review approval.

- Sync branches can only be created on Gerrit, and require filing
  a ticket, see associated bug for details.

Use `git log origin/upstream/master..fuchsia-rfc-0153` to see the detail log
of changes instead.

To facilite sync branch creation and management, the commit message of
patches should following these conventions:

- Patches that were cherry-picked from upstream should have a line that
  starts with `Upstream-Cherry-Pick: <COMMIT>` added to their original
  commit message.

- Patches that were cherry-picked from the upstream GitHub pull requests
  should have a line that starts with  `Upstream-GitHub-PR: <URL>`
  pointing to the corresponding pull request.

- Patches that should not be sent upstream should have a line that
  starts with `Fuchsia-Only: <REASON>`. These should only matter for
  Fuchsia specific documentation (such as this file), or development
  scripts.

- Non-trivial changes that address a specific feature should be provided
  as a series of small patches whose commit messages all include a line
  that starts with `Fuchsia-Topic: <name>`, where `<name>` is a small
  identifier describing the common feature (e.g. `faster-manifest-parser`)
  described by the list in the next section of this README.fuchsia file.

  This will allow collecting the commits to send them as upstream pull
  requests (after removing these lines from the commit message), or to
  re-order them during sync-branch rebase operations.

Fuchsia-specific scripts or data files should go under `misc/fuchsia/`.