From 58a59fdfbca47f6a6d3fd738ccc5f978d554209f Mon Sep 17 00:00:00 2001 From: Mike Frysinger Date: Wed, 20 Aug 2025 17:08:03 -0400 Subject: CONTRIBUTING: rename doc per Google OSS policies Google OSS policies say to name this "CONTRIBUTING.md". Change-Id: I037f52a443caacc89868b7c14af91dd3d1b681a9 Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/499761 Reviewed-by: Gavin Mak Tested-by: Mike Frysinger Commit-Queue: Mike Frysinger --- .github/workflows/close-pull-request.yml | 2 +- CONTRIBUTING.md | 190 +++++++++++++++++++++++++++++++ README.md | 2 +- SUBMITTING_PATCHES.md | 190 ------------------------------- 4 files changed, 192 insertions(+), 192 deletions(-) create mode 100644 CONTRIBUTING.md delete mode 100644 SUBMITTING_PATCHES.md diff --git a/.github/workflows/close-pull-request.yml b/.github/workflows/close-pull-request.yml index dff055fc..f64e95ac 100644 --- a/.github/workflows/close-pull-request.yml +++ b/.github/workflows/close-pull-request.yml @@ -18,5 +18,5 @@ jobs: Thanks for your contribution! Unfortunately, we don't use GitHub pull requests to manage code contributions to this repository. - Instead, please see [README.md](../blob/HEAD/SUBMITTING_PATCHES.md) + Instead, please see [README.md](../blob/HEAD/CONTRIBUTING.md) which provides full instructions on how to get involved. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..671a43fe --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,190 @@ +# Submitting Changes + +Here's a short overview of the process. + +* Make small logical changes. +* [Provide a meaningful commit message][commit-message-style]. +* Make sure all code is under the Apache License, 2.0. +* Publish your changes for review. + * `git push origin HEAD:refs/for/main` +* Make corrections if requested. +* [Verify your changes on Gerrit.](#verify) +* [Send to the commit queue for testing & merging.](#cq) + +[TOC] + +## Long Version + +I wanted a file describing how to submit patches for repo, +so I started with the one found in the core Git distribution +(Documentation/SubmittingPatches), which itself was based on the +patch submission guidelines for the Linux kernel. + +However there are some differences, so please review and familiarize +yourself with the following relevant bits. + + +## Make separate commits for logically separate changes. + +Unless your patch is really trivial, you should not be sending out a patch that +was generated between your working tree and your commit head. +Instead, always make a commit with a complete +[commit message][commit-message-style] and generate a series of patches from +your repository. +It is a good discipline. + +Describe the technical detail of the change(s). + +If your description starts to get too long, that's a sign that you +probably need to split up your commit to finer grained pieces. + + +## Linting and formatting code + +Lint any changes by running: +```sh +$ tox -e lint -- file.py +``` + +And format with: +```sh +$ tox -e format -- file.py +``` + +Or format everything: +```sh +$ tox -e format +``` + +Repo uses [black](https://black.readthedocs.io/) with line length of 80 as its +formatter and flake8 as its linter. Repo also follows +[Google's Python Style Guide]. + +There should be no new errors or warnings introduced. + +Warnings that cannot be avoided without going against the Google Style Guide +may be suppressed inline individally using a `# noqa` comment as described +in the [flake8 documentation]. + +If there are many occurrences of the same warning, these may be suppressed for +the entire project in the included `.flake8` file. + +[Google's Python Style Guide]: https://google.github.io/styleguide/pyguide.html +[PEP 8]: https://www.python.org/dev/peps/pep-0008/ +[flake8 documentation]: https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html#in-line-ignoring-errors + +## Running tests + +We use [pytest](https://pytest.org/) and [tox](https://tox.readthedocs.io/) for +running tests. You should make sure to install those first. + +To run the full suite against all supported Python versions, simply execute: +```sh +$ tox -p auto +``` + +We have [`./run_tests`](./run_tests) which is a simple wrapper around `pytest`: +```sh +# Run the full suite against the default Python version. +$ ./run_tests +# List each test as it runs. +$ ./run_tests -v + +# Run a specific unittest module (and all tests in it). +$ ./run_tests tests/test_git_command.py + +# Run a specific testsuite in a specific unittest module. +$ ./run_tests tests/test_editor.py::EditString + +# Run a single test. +$ ./run_tests tests/test_editor.py::EditString::test_cat_editor + +# List all available tests. +$ ./run_tests --collect-only + +# Run a single test using substring match. +$ ./run_tests -k test_cat_editor +``` + +The coverage isn't great currently, but it should still be run for all commits. +Adding more unittests for changes you make would be greatly appreciated :). +Check out the [tests/](./tests/) subdirectory for more details. + + +## Check the license + +repo is licensed under the Apache License, 2.0. + +Because of this licensing model *every* file within the project +*must* list the license that covers it in the header of the file. +Any new contributions to an existing file *must* be submitted under +the current license of that file. Any new files *must* clearly +indicate which license they are provided under in the file header. + +Please verify that you are legally allowed and willing to submit your +changes under the license covering each file *prior* to submitting +your patch. It is virtually impossible to remove a patch once it +has been applied and pushed out. + + +## Sending your patches. + +Do not email your patches to anyone. + +Instead, login to the Gerrit Code Review tool at: + + https://gerrit-review.googlesource.com/ + +Ensure you have completed one of the necessary contributor +agreements, providing documentation to the project maintainers that +they have right to redistribute your work under the Apache License: + + https://gerrit-review.googlesource.com/#/settings/agreements + +Ensure you have obtained an HTTP password to authenticate: + + https://gerrit-review.googlesource.com/new-password + +Ensure that you have the local commit hook installed to automatically +add a ChangeId to your commits: + + curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://gerrit-review.googlesource.com/tools/hooks/commit-msg + chmod +x `git rev-parse --git-dir`/hooks/commit-msg + +If you have already committed your changes you will need to amend the commit +to get the ChangeId added. + + git commit --amend + +Push your patches over HTTPS to the review server, possibly through +a remembered remote to make this easier in the future: + + git config remote.review.url https://gerrit-review.googlesource.com/git-repo + git config remote.review.push HEAD:refs/for/main + + git push review + +You will be automatically emailed a copy of your commits, and any +comments made by the project maintainers. + + +## Make changes if requested + +The project maintainer who reviews your changes might request changes to your +commit. If you make the requested changes you will need to amend your commit +and push it to the review server again. + + +## Verify your changes on Gerrit {#verify} + +After you receive a Code-Review+2 from the maintainer, select the Verified +button on the Gerrit page for the change. This verifies that you have tested +your changes and notifies the maintainer that they are ready to be submitted. + +## Merge your changes via the commit queue {#cq} + +Once a change is ready to be merged, select the Commit-Queue+2 setting on the +Gerrit page for it. This tells the CI system to test the change, and if it +passes all the checks, automatically merges it. + +[commit-message-style]: https://chris.beams.io/posts/git-commit/ diff --git a/README.md b/README.md index 5c5ee5d9..258491b0 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ that you can put anywhere in your path. * Docs: * [repo Manifest Format](./docs/manifest-format.md) * [repo Hooks](./docs/repo-hooks.md) -* [Submitting patches](./SUBMITTING_PATCHES.md) +* [Contributing](./CONTRIBUTING.md) * Running Repo in [Microsoft Windows](./docs/windows.md) * GitHub mirror: * Postsubmit tests: diff --git a/SUBMITTING_PATCHES.md b/SUBMITTING_PATCHES.md deleted file mode 100644 index 671a43fe..00000000 --- a/SUBMITTING_PATCHES.md +++ /dev/null @@ -1,190 +0,0 @@ -# Submitting Changes - -Here's a short overview of the process. - -* Make small logical changes. -* [Provide a meaningful commit message][commit-message-style]. -* Make sure all code is under the Apache License, 2.0. -* Publish your changes for review. - * `git push origin HEAD:refs/for/main` -* Make corrections if requested. -* [Verify your changes on Gerrit.](#verify) -* [Send to the commit queue for testing & merging.](#cq) - -[TOC] - -## Long Version - -I wanted a file describing how to submit patches for repo, -so I started with the one found in the core Git distribution -(Documentation/SubmittingPatches), which itself was based on the -patch submission guidelines for the Linux kernel. - -However there are some differences, so please review and familiarize -yourself with the following relevant bits. - - -## Make separate commits for logically separate changes. - -Unless your patch is really trivial, you should not be sending out a patch that -was generated between your working tree and your commit head. -Instead, always make a commit with a complete -[commit message][commit-message-style] and generate a series of patches from -your repository. -It is a good discipline. - -Describe the technical detail of the change(s). - -If your description starts to get too long, that's a sign that you -probably need to split up your commit to finer grained pieces. - - -## Linting and formatting code - -Lint any changes by running: -```sh -$ tox -e lint -- file.py -``` - -And format with: -```sh -$ tox -e format -- file.py -``` - -Or format everything: -```sh -$ tox -e format -``` - -Repo uses [black](https://black.readthedocs.io/) with line length of 80 as its -formatter and flake8 as its linter. Repo also follows -[Google's Python Style Guide]. - -There should be no new errors or warnings introduced. - -Warnings that cannot be avoided without going against the Google Style Guide -may be suppressed inline individally using a `# noqa` comment as described -in the [flake8 documentation]. - -If there are many occurrences of the same warning, these may be suppressed for -the entire project in the included `.flake8` file. - -[Google's Python Style Guide]: https://google.github.io/styleguide/pyguide.html -[PEP 8]: https://www.python.org/dev/peps/pep-0008/ -[flake8 documentation]: https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html#in-line-ignoring-errors - -## Running tests - -We use [pytest](https://pytest.org/) and [tox](https://tox.readthedocs.io/) for -running tests. You should make sure to install those first. - -To run the full suite against all supported Python versions, simply execute: -```sh -$ tox -p auto -``` - -We have [`./run_tests`](./run_tests) which is a simple wrapper around `pytest`: -```sh -# Run the full suite against the default Python version. -$ ./run_tests -# List each test as it runs. -$ ./run_tests -v - -# Run a specific unittest module (and all tests in it). -$ ./run_tests tests/test_git_command.py - -# Run a specific testsuite in a specific unittest module. -$ ./run_tests tests/test_editor.py::EditString - -# Run a single test. -$ ./run_tests tests/test_editor.py::EditString::test_cat_editor - -# List all available tests. -$ ./run_tests --collect-only - -# Run a single test using substring match. -$ ./run_tests -k test_cat_editor -``` - -The coverage isn't great currently, but it should still be run for all commits. -Adding more unittests for changes you make would be greatly appreciated :). -Check out the [tests/](./tests/) subdirectory for more details. - - -## Check the license - -repo is licensed under the Apache License, 2.0. - -Because of this licensing model *every* file within the project -*must* list the license that covers it in the header of the file. -Any new contributions to an existing file *must* be submitted under -the current license of that file. Any new files *must* clearly -indicate which license they are provided under in the file header. - -Please verify that you are legally allowed and willing to submit your -changes under the license covering each file *prior* to submitting -your patch. It is virtually impossible to remove a patch once it -has been applied and pushed out. - - -## Sending your patches. - -Do not email your patches to anyone. - -Instead, login to the Gerrit Code Review tool at: - - https://gerrit-review.googlesource.com/ - -Ensure you have completed one of the necessary contributor -agreements, providing documentation to the project maintainers that -they have right to redistribute your work under the Apache License: - - https://gerrit-review.googlesource.com/#/settings/agreements - -Ensure you have obtained an HTTP password to authenticate: - - https://gerrit-review.googlesource.com/new-password - -Ensure that you have the local commit hook installed to automatically -add a ChangeId to your commits: - - curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://gerrit-review.googlesource.com/tools/hooks/commit-msg - chmod +x `git rev-parse --git-dir`/hooks/commit-msg - -If you have already committed your changes you will need to amend the commit -to get the ChangeId added. - - git commit --amend - -Push your patches over HTTPS to the review server, possibly through -a remembered remote to make this easier in the future: - - git config remote.review.url https://gerrit-review.googlesource.com/git-repo - git config remote.review.push HEAD:refs/for/main - - git push review - -You will be automatically emailed a copy of your commits, and any -comments made by the project maintainers. - - -## Make changes if requested - -The project maintainer who reviews your changes might request changes to your -commit. If you make the requested changes you will need to amend your commit -and push it to the review server again. - - -## Verify your changes on Gerrit {#verify} - -After you receive a Code-Review+2 from the maintainer, select the Verified -button on the Gerrit page for the change. This verifies that you have tested -your changes and notifies the maintainer that they are ready to be submitted. - -## Merge your changes via the commit queue {#cq} - -Once a change is ready to be merged, select the Commit-Queue+2 setting on the -Gerrit page for it. This tells the CI system to test the change, and if it -passes all the checks, automatically merges it. - -[commit-message-style]: https://chris.beams.io/posts/git-commit/ -- cgit v1.2.3-54-g00ecf