Add README.fuchsia
Fuchsia-Only: Documentation
Bug: 91545
Original-Change-Id: I6c8261106d5a21c132644b4e957201b393a67d26
Original-Change-Id: I86274252e4930b72a2866dd6527d7d5ed2d4dca4
Original-Change-Id: I4182bad709bf4758a1b0f47006a19807bf01a7b0
Original-Change-Id: Ic3abe9985c35a0be73964f0701e6f5670c45bf9a
Original-Change-Id: I6d55df2048b84ca859d7a7242c815e6d6db6da1a
Change-Id: Ia591e68f30aaa2faeb78c9b08e34b66a1cd8132f
Reviewed-on: https://fuchsia-review.googlesource.com/c/third_party/github.com/ninja-build/ninja/+/970032
Commit-Queue: Auto-Submit <auto-submit@fuchsia-infra.iam.gserviceaccount.com>
Reviewed-by: David Fang <fangism@google.com>
Reviewed-by: Jay Zhuang <jayzhuang@google.com>
Fuchsia-Auto-Submit: David Turner <digit@google.com>
Reviewed-by: Tyler Mandry <tmandry@google.com>
diff --git a/README.fuchsia b/README.fuchsia
new file mode 100644
index 0000000..9317b22
--- /dev/null
+++ b/README.fuchsia
@@ -0,0 +1,87 @@
+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 `main` branch of
+ `https://fuchsia.googlesource.com/third_party/github.com/ninja-build/ninja`
+
+- All patches need to be uploaded to Gerrit for review approval.
+ (https://fuchsia-review.googlesource.com).
+
+- Sync branches can only be created on Gerrit, and require filing
+ a ticket, see associated bug for details.
+
+Use `git log origin/upstream/master..main` 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/`.
+
+List of Fuchsia-Topic items:
+
+multi-line-status
+ Improve the status display in smart terminals to include a list of
+ the oldest pending commands that are still running. This feature is
+ controlled by setting NINJA_STATUS_MAX_COMMANDS in the
+ environment to a decimal value that is >= 1.
+
+advanced-ipc
+ Provide support for advanced inter-process communication using
+ named pipes (on Win32) or unix domain sockets (on Posix). This
+ will be used to implement both the `persistent-mode` feature
+ and the `jobserver-support` feature.
+
+persistent-mode
+ Allow the Ninja process to run in daemon mode after parsing the
+ Ninja build plan, until a .ninja file is changed or some fixed
+ expiration time, in order to start future `ninja` invocations
+ immediately (instead of spending several seconds to re-load the
+ build plan every time).
+ Requires: advanced-ipc
+
+jobserver-support
+ Allow Ninja to act as both a GNU Make jobserver client
+ (when invoking from other build systems), and a server
+ (when invoking sub-commands).
+ Requires: advanced-ipc
