mirror of
https://fuchsia.googlesource.com/third_party/pigweed.googlesource.com/pigweed/pigweed
synced 2024-09-20 13:51:05 +00:00
72cae432f5
This migrates our legacy Markdown to Restructured Text (RST). Now that we have a website, we don't have to rely on rendering our docs on Gerrit and GitHub, and can instead point at our webpage. This enables 1. Upgrading to a new Sphinx - our current version is 2 years old. 2. Using more sophisticated constructs like "note" 3. Adding custom CSS rules Change-Id: I8153322efbcb307c1ca1ee3392b67f30f365f78c Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/40480 Reviewed-by: Armando Montanez <amontanez@google.com> Commit-Queue: Keir Mierle <keir@google.com> Pigweed-Auto-Submit: Keir Mierle <keir@google.com>
237 lines
9.1 KiB
ReStructuredText
237 lines
9.1 KiB
ReStructuredText
.. _docs-contributing:
|
|
|
|
============
|
|
Contributing
|
|
============
|
|
We'd love to accept your patches and contributions to Pigweed. There are just a
|
|
few small guidelines you need to follow. Before making or sending major
|
|
changes, please reach out on the `mailing list
|
|
<https://groups.google.com/forum/#!forum/pigweed>`_ first to ensure the changes
|
|
make sense for upstream. We generally go through a design phase before making
|
|
large changes.
|
|
|
|
Before participating in our community, please take a moment to review our
|
|
:ref:`docs-code-of-conduct`. We expect everyone who interacts with the project
|
|
to respect these guidelines.
|
|
|
|
Pigweed contribution overview
|
|
-----------------------------
|
|
|
|
#. One-time contributor setup:
|
|
|
|
- Sign the `Contributor License Agreement <https://cla.developers.google.com/>`_.
|
|
- Verify that your Git user email (git config user.email) is either Google
|
|
Account email or an Alternate email for the Google account used to sign
|
|
the CLA (Manage Google account → Personal Info → email)
|
|
- Install the Gerrit commit hook to automatically add a ``Change-Id: ...``
|
|
line to your commit
|
|
- Install the Pigweed presubmit check hook with ``pw presubmit --install``
|
|
|
|
#. Ensure all files include the correct copyright and license headers
|
|
#. Include any necessary changes to the documentation
|
|
#. Run :ref:`module-pw_presubmit` to detect style or compilation issues before
|
|
uploading
|
|
#. Upload the change with ``git push origin HEAD:refs/for/master``
|
|
#. Address any reviewer feedback by amending the commit (``git commit --amend``)
|
|
#. Submit change to CI builders to merge. If you are not part of Pigweed's
|
|
core team, you can ask the reviewer to add the `+2 CQ` vote, which will
|
|
trigger a rebase and submit once the builders pass
|
|
|
|
.. note::
|
|
|
|
If you have any trouble with this flow, reach out in our `chat room
|
|
<https://discord.gg/M9NSeTA>`_ or on the `mailing list
|
|
<https://groups.google.com/forum/#!forum/pigweed>`_ for help.
|
|
|
|
Contributor License Agreement
|
|
-----------------------------
|
|
Contributions to this project must be accompanied by a Contributor License
|
|
Agreement. You (or your employer) retain the copyright to your contribution;
|
|
this simply gives us permission to use and redistribute your contributions as
|
|
part of the project. Head over to <https://cla.developers.google.com/> to see
|
|
your current agreements on file or to sign a new one.
|
|
|
|
You generally only need to submit a CLA once, so if you've already submitted one
|
|
(even if it was for a different project), you probably don't need to do it
|
|
again.
|
|
|
|
Gerrit Commit Hook
|
|
------------------
|
|
Gerrit requires all changes to have a ``Change-Id`` tag at the bottom of each
|
|
commit message. You should set this up to be done automatically using the
|
|
instructions below.
|
|
|
|
**Linux/macOS**
|
|
|
|
.. code:: bash
|
|
|
|
$ f=`git rev-parse --git-dir`/hooks/commit-msg ; mkdir -p $(dirname $f) ; curl -Lo $f https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x $f
|
|
|
|
**Windows**
|
|
|
|
Download `the Gerrit commit hook
|
|
<https://gerrit-review.googlesource.com/tools/hooks/commit-msg>`_ and then copy
|
|
it to the ``.git\hooks`` directory in the Pigweed repository.
|
|
|
|
.. code::
|
|
|
|
copy %HOMEPATH%\Downloads\commit-msg %HOMEPATH%\pigweed\.git\hooks\commit-msg
|
|
|
|
Documentation
|
|
-------------
|
|
|
|
All Pigweed changes must either
|
|
|
|
#. Include updates to documentation, or
|
|
#. Include ``No-Docs-Update-Reason: <reason>`` in the commit message or a
|
|
Gerrit comment on the CL. For example:
|
|
|
|
* ``No-Docs-Update-Reason: formatting tweaks``
|
|
* ``No-Docs-Update-Reason: internal cleanups``
|
|
* ``No-Docs-Update-Reason: bugfix``
|
|
|
|
It's acceptable to only document new changes in an otherwise underdocumented
|
|
module, but it's not acceptable to not document new changes because the module
|
|
doesn't have any other documentation.
|
|
|
|
Code Reviews
|
|
------------
|
|
All Pigweed development happens on Gerrit, following the `typical Gerrit
|
|
development workflow <http://ceres-solver.org/contributing.html>`_. Consult the
|
|
`Gerrit User Guide
|
|
<https://gerrit-documentation.storage.googleapis.com/Documentation/2.12.3/intro-user.html>`_
|
|
for more information on using Gerrit.
|
|
|
|
In the future we may support GitHub pull requests, but until that time we will
|
|
close GitHub pull requests and ask that the changes be uploaded to Gerrit
|
|
instead.
|
|
|
|
Community Guidelines
|
|
--------------------
|
|
This project follows `Google's Open Source Community Guidelines
|
|
<https://opensource.google/conduct/>`_ and the :ref:`docs-code-of-conduct`.
|
|
|
|
Source Code Headers
|
|
-------------------
|
|
Every Pigweed file containing source code must include copyright and license
|
|
information. This includes any JS/CSS files that you might be serving out to
|
|
browsers.
|
|
|
|
Apache header for C and C++ files:
|
|
|
|
.. code:: none
|
|
|
|
// Copyright 2021 The Pigweed Authors
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
|
|
// use this file except in compliance with the License. You may obtain a copy of
|
|
// the License at
|
|
//
|
|
// https://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
// License for the specific language governing permissions and limitations under
|
|
// the License.
|
|
|
|
Apache header for Python and GN files:
|
|
|
|
.. code:: none
|
|
|
|
# Copyright 2020 The Pigweed Authors
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
|
|
# use this file except in compliance with the License. You may obtain a copy of
|
|
# the License at
|
|
#
|
|
# https://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
# License for the specific language governing permissions and limitations under
|
|
# the License.
|
|
|
|
Presubmit Checks and Continuous Integration
|
|
-------------------------------------------
|
|
All Pigweed change lists (CLs) must adhere to Pigweed's style guide and pass a
|
|
suite of automated builds, tests, and style checks to be merged upstream. Much
|
|
of this checking is done using Pigweed's ``pw_presubmit`` module by automated
|
|
builders. These builders run before each Pigweed CL is submitted and in our
|
|
continuous integration infrastructure (see `Pigweed's build console
|
|
<https://ci.chromium.org/p/pigweed/g/pigweed/console>`_).
|
|
|
|
Running Presubmit Checks
|
|
------------------------
|
|
To run automated presubmit checks on a pending CL, click the ``CQ DRY RUN``
|
|
button in the Gerrit UI. The results appear in the Tryjobs section, below the
|
|
source listing. Jobs that passed are green; jobs that failed are red.
|
|
|
|
If all checks pass, you will see a ``Dry run: This CL passed the CQ dry run.``
|
|
comment on your change. If any checks fail, you will see a ``Dry run: Failed
|
|
builds:`` message. All failures must be addressed before submitting.
|
|
|
|
In addition to the publicly visible presubmit checks, Pigweed runs internal
|
|
presubmit checks that are only visible within Google. If any these checks fail,
|
|
external developers will see a ``Dry run: Failed builds:`` comment on the CL,
|
|
even if all visible checks passed. Reach out to the Pigweed team for help
|
|
addressing these issues.
|
|
|
|
Project Presubmit Checks
|
|
------------------------
|
|
In addition to Pigweed's presubmit checks, some projects that use Pigweed run
|
|
their presubmit checks in Pigweed's infrastructure. This supports a development
|
|
flow where projects automatically update their Pigweed submodule if their tests
|
|
pass. If a project cannot build against Pigweed's tip-of-tree, it will stay on
|
|
a fixed Pigweed revision until the issues are fixed. See the `sample project
|
|
<https://pigweed.googlesource.com/pigweed/sample_project/>`_ for an example of
|
|
this.
|
|
|
|
Pigweed does its best to keep builds passing for dependent projects. In some
|
|
circumstances, the Pigweed maintainers may choose to merge changes that break
|
|
dependent projects. This will only be done if
|
|
|
|
* a feature or fix is needed urgently in Pigweed or for a different project,
|
|
and
|
|
* the project broken by the change does not imminently need Pigweed updates.
|
|
|
|
The downstream project will continue to build against their last working
|
|
revision of Pigweed until the incompatibilities are fixed.
|
|
|
|
In these situations, Pigweed's commit queue submission process will fail for all
|
|
changes. If a change passes all presubmit checks except for known failures, the
|
|
Pigweed team may permit manual submission of the CL. Contact the Pigweed team
|
|
for submission approval.
|
|
|
|
Running local presubmits
|
|
------------------------
|
|
To speed up the review process, consider adding :ref:`module-pw_presubmit` as a
|
|
git push hook using the following command:
|
|
|
|
**Linux/macOS**
|
|
|
|
.. code:: bash
|
|
|
|
$ pw presubmit --install
|
|
|
|
This will be effectively the same as running the following command before every
|
|
``git push``:
|
|
|
|
.. code:: bash
|
|
|
|
$ pw presubmit
|
|
|
|
|
|
.. image:: ../pw_presubmit/docs/pw_presubmit_demo.gif
|
|
:width: 800
|
|
:alt: pw presubmit demo
|
|
|
|
If you ever need to bypass the presubmit hook (due to it being broken, for
|
|
example) you may push using this command:
|
|
|
|
.. code:: bash
|
|
|
|
$ git push origin HEAD:refs/for/master --no-verify
|
|
|