Skip to content

Commit 9152292

Browse files
mhuckamhucka
committed
Add more guidance to CONTRIBUTING.md
This adds more general information, along with an important warning about AI-generated code.
1 parent d305381 commit 9152292

1 file changed

Lines changed: 108 additions & 23 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 108 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,123 @@
11
# How to contribute
22

3-
We'd love to accept your patches and contributions to this project.
4-
We do have some guidelines to follow, covered in this document, but don't
5-
worry about (or expect to) get everything right the first time!
6-
Create a pull request and we'll nudge you in the right direction. Please also
7-
note that we have a [code of conduct](CODE_OF_CONDUCT.md) to make TUnits an
8-
open and welcoming environment.
3+
We'd love to accept your patches and contributions to this project. We do have
4+
some guidelines to follow, covered in this document, but don't be concerned
5+
about getting everything right the first time! Create a pull request (discussed
6+
below) and we'll nudge you in the right direction.
97

108
## Before you begin
119

1210
### Sign our Contributor License Agreement
1311

14-
Contributions to this project must be accompanied by a
15-
[Contributor License Agreement](https://cla.developers.google.com/about) (CLA).
16-
You (or your employer) retain the copyright to your contribution; this simply
17-
gives us permission to use and redistribute your contributions as part of the
18-
project.
12+
Contributions to this project must be accompanied by a [Contributor License
13+
Agreement](https://cla.developers.google.com/about) (CLA). You (or your
14+
employer) retain the copyright to your contribution; the CLA simply gives us
15+
permission to use and redistribute your contributions as part of the project.
16+
Please visit https://cla.developers.google.com/ to see your current agreements
17+
on file or to sign a new one. You generally only need to submit a Google CLA
18+
once, so if you've already submitted one (even if it was for a different
19+
project), you probably don't need to do it again.
1920

20-
If you or your current employer have already signed the Google CLA (even if it
21-
was for a different project), you probably don't need to do it again.
22-
23-
Visit <https://cla.developers.google.com/> to see your current agreements or to
24-
sign a new one.
21+
> [!WARNING]
22+
> Please note carefully clauses [#5](https://cla.developers.google.com/about/google-corporate#:~:text=You%20represent%20that%20each%20of%20Your%20Contributions%20is%20Your%20original%20creation)
23+
> and [#7](https://cla.developers.google.com/about/google-corporate#:~:text=Should%20You%20wish%20to%20submit%20work%20that%20is%20not%20Your%20original%20creation%2C%20You%20may%20submit%20it%20to%20Google%20separately)
24+
> in the CLA. Any code that you contribute to this project must be **your**
25+
> original creation. Code generated by artificial intelligence tools **does
26+
> not** qualify as your original creation.
2527
2628
### Review our community guidelines
2729

28-
This project follows
29-
[Google's Open Source Community Guidelines](https://opensource.google/conduct/).
30+
We have a [code of conduct](CODE_OF_CONDUCT.md) to make the TypedUnits project
31+
an open and welcoming community environment. Please make sure to read and abide
32+
by the code of conduct.
3033

3134
## Contribution process
3235

33-
### Code reviews
34-
3536
All submissions, including submissions by project members, require review. We
36-
use GitHub pull requests for this purpose. Consult
37-
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
38-
information on using pull requests.
37+
use the tools provided by GitHub for [pull
38+
requests](https://help.github.com/articles/about-pull-requests/) for this
39+
purpose. The preferred manner for submitting pull requests is to fork the
40+
TypedUnits [repository](https://github.com/quantumlib/TypedUnits), create a [git
41+
branch](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) in
42+
this fork to do your work, and when ready, create a pull request from this
43+
branch to the main TypedUnits repository. The subsections below describe the
44+
process in more detail.
45+
46+
Pleae make sure to follow the [Google Style
47+
Guides](https://google.github.io/styleguide/) in your code, particularly the
48+
[style guide for Python](https://google.github.io/styleguide/pyguide.html).
49+
50+
### Repository forks
51+
52+
1. Fork the TypedUnits repository (you can use the _Fork_ button in upper right
53+
corner of the [repository page](https://github.com/quantumlib/TypedUnits)).
54+
Forking creates a new GitHub repo at the location
55+
`https://github.com/USERNAME/TypedUnits`, where `USERNAME` is your GitHub
56+
user name.
57+
58+
1. Clone (using `git clone`) or otherwise download your forked repository to
59+
your local computer, so that you have a local copy where you can do your
60+
development work using your preferred editor and development tools.
61+
62+
1. Check out the `main` branch and create a new git branch from `main`:
63+
64+
```shell
65+
git checkout main -b YOUR_BRANCH_NAME
66+
```
67+
68+
where `YOUR_BRANCH_NAME` is the name of your new branch.
69+
70+
### Development and testing
71+
72+
Do your work and `git commit` your changes to your branch as needed.
73+
74+
We use several tools to test code and perform other activities such as checking
75+
formatting against the style guidelines. You can run those tools locally during
76+
development. Wrapper scripts are located in the [`check/`](./check/)
77+
subdirectory to simplify running the tools.
78+
79+
* Run `check/pytest` to run the Pytest suite
80+
* Run `check/mypy` to run the Mypy type checker
81+
* Run `check/pylint` to run the Pylint code linter
82+
83+
### Pull requests and code reviews
84+
85+
1. If your local copy has drifted out of sync with the `main` branch of the
86+
main TypedUnits repository, you may need to merge the latest changes into
87+
your branch. To do this, first update your local `main` and then merge your
88+
local `main` into your branch:
89+
90+
```shell
91+
# Track the upstream repo (if your local repo hasn't):
92+
git remote add upstream https://github.com/quantumlib/TypedUnits.git
93+
94+
# Update your local main.
95+
git fetch upstream
96+
git checkout main
97+
git merge upstream/main
98+
# Merge local main into your branch.
99+
git checkout YOUR_BRANCH_NAME
100+
git merge main
101+
```
102+
103+
If git reports conflicts during one or both of these merge processes, you
104+
may need to [resolve the merge conflicts](
105+
https://docs.github.com/articles/about-merge-conflicts) before continuing.
106+
107+
1. Finally, push your changes to your fork of the TypedUnits repo on GitHub:
108+
109+
```shell
110+
git push origin YOUR_BRANCH_NAME
111+
```
112+
113+
1. Now when you navigate to the TypedUnits repository on GitHub
114+
(https://github.com/quantumlib/TypedUnits), you should see the option to
115+
create a new pull request from your forked repository. Alternatively, you
116+
can create the pull request by navigating to the "Pull requests" tab near
117+
the top of the page, and selecting the appropriate branches.
118+
119+
1. A reviewer from the TypedUnits team will comment on your code and may ask for
120+
changes. You can perform the necessary changes locally, commit them to your
121+
branch as usual, and then push changes to your fork on GitHub following the
122+
same process as above. When you do that, GitHub will update the code in the
123+
pull request automatically.

0 commit comments

Comments
 (0)