Skip to content

Commit 2d62170

Browse files
mhuckamhucka
authored
Add miscellenous repository files for best practices (#48)
This adds some miscellaneous files, like a security policy file, in order to improve some of the GitHub best practices indicators on https://github.com/quantumlib/TypedUnits/community It also fills out `CONTRIBUTING.md` with more detailed information (based on other quantumlib projects), and adds an important warning about contributions using AI-based code generation.
2 parents 564b9dd + 04ac8d2 commit 2d62170

File tree

4 files changed

+251
-23
lines changed

4 files changed

+251
-23
lines changed

‎.github/SECURITY.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Reporting security issues
2+
3+
The TypedUnits developers and community take security bugs in TypedUnits
4+
seriously. We appreciate your efforts to disclose your findings responsibly, and
5+
will make every effort to acknowledge your contributions.
6+
7+
Please **do not** use GitHub issues to report security vulnerabilities; GitHub
8+
issues are public, and doing so could allow someone to exploit the information
9+
before the problem can be addressed. Instead, please use the GitHub ["Report a
10+
Vulnerability"](https://github.com/quantumlib/TypedUnits/security/advisories/new)
11+
interface from the _Security_ tab of the TypedUnits repository.
12+
13+
Please report security issues in third-party modules to the person or team
14+
maintaining the module rather than the TypedUnits project stewards, unless you
15+
believe that some action needs to be taken with TypedUnits in order to guard
16+
against the effects of a security vulnerability in a third-party module.
17+
18+
## Responses to security reports
19+
20+
The project stewards at Google Quantum AI will send a response indicating the
21+
next steps in handling your report. After the initial reply to your report, the
22+
project stewards will keep you informed of the progress towards a fix and full
23+
announcement, and may ask for additional information or guidance.
24+
25+
## Additional points of contact
26+
27+
Please contact the project stewards at Google Quantum AI via email at
28+
quantum-oss-maintainers@google.com if you have questions or other concerns. If
29+
for any reason you are uncomfortable reaching out to the project stewards,
30+
please email opensource@google.com.

‎CODE_OF_CONDUCT.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to making participation in our project and
7+
our community a harassment-free experience for everyone, regardless of age, body
8+
size, disability, ethnicity, gender identity and expression, level of
9+
experience, education, socio-economic status, nationality, personal appearance,
10+
race, religion, or sexual identity and orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
* Using welcoming and inclusive language
18+
* Being respectful of differing viewpoints and experiences
19+
* Gracefully accepting constructive criticism
20+
* Focusing on what is best for the community
21+
* Showing empathy towards other community members
22+
23+
Examples of unacceptable behavior by participants include:
24+
25+
* The use of sexualized language or imagery and unwelcome sexual attention or
26+
advances
27+
* Trolling, insulting/derogatory comments, and personal or political attacks
28+
* Public or private harassment
29+
* Publishing others' private information, such as a physical or electronic
30+
address, without explicit permission
31+
* Other conduct which could reasonably be considered inappropriate in a
32+
professional setting
33+
34+
## Our Responsibilities
35+
36+
Project maintainers are responsible for clarifying the standards of acceptable
37+
behavior and are expected to take appropriate and fair corrective action in
38+
response to any instances of unacceptable behavior.
39+
40+
Project maintainers have the right and responsibility to remove, edit, or reject
41+
comments, commits, code, wiki edits, issues, and other contributions that are
42+
not aligned to this Code of Conduct, or to ban temporarily or permanently any
43+
contributor for other behaviors that they deem inappropriate, threatening,
44+
offensive, or harmful.
45+
46+
## Scope
47+
48+
This Code of Conduct applies both within project spaces and in public spaces
49+
when an individual is representing the project or its community. Examples of
50+
representing a project or community include using an official project e-mail
51+
address, posting via an official social media account, or acting as an appointed
52+
representative at an online or offline event. Representation of a project may be
53+
further defined and clarified by project maintainers.
54+
55+
This Code of Conduct also applies outside the project spaces when the Project
56+
Stewards have a reasonable belief that an individual's behavior may have a
57+
negative impact on the project or its community.
58+
59+
## Conflict Resolution
60+
61+
We do not believe that all conflict is bad; healthy debate and disagreement
62+
often yield positive results. However, it is never okay to be disrespectful or
63+
to engage in behavior that violates the project’s Code of Conduct.
64+
65+
If you see someone violating the Code of Conduct, you are encouraged to address
66+
the behavior directly with those involved. Many issues can be resolved quickly
67+
and easily, and this gives people more control over the outcome of their
68+
dispute. If you are unable to resolve the matter for any reason, or if the
69+
behavior is threatening or harassing, report it. We are dedicated to providing
70+
an environment where participants feel welcome and safe.
71+
72+
Reports should be directed to quantumai-oss-maintainers@googlegroups.com,
73+
the project stewards at Google Quantum AI. They will then work with a committee
74+
consisting of representatives from the Open Source Programs Office and the
75+
Google Open Source Strategy team. If for any reason you are uncomfortable
76+
reaching out to the Project Stewards, please email opensource@google.com.
77+
78+
We will investigate every complaint, but you may not receive a direct response.
79+
We will use our discretion in determining when and how to follow up on reported
80+
incidents, which may range from not taking action to permanent expulsion from
81+
the project and project-sponsored spaces. We will notify the accused of the
82+
report and provide them an opportunity to discuss it before any action is taken.
83+
The identity of the reporter will be omitted from the details of the report
84+
supplied to the accused. In potentially harmful situations, such as ongoing
85+
harassment or threats to anyone's safety, we may take action without notice.
86+
87+
## Attribution
88+
89+
This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
90+
available at
91+
https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

‎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.

‎SUPPORT.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Support
2+
3+
Thank you for your interest in this project! If you are experiencing problems
4+
or have questions, the following are some suggestions for how to get help.
5+
6+
> [!NOTE]
7+
> Before participating in our community, please read our [code of
8+
> conduct](CODE_OF_CONDUCT.md). By interacting with this repository,
9+
> organization, or community, you agree to abide by its terms.
10+
11+
## Report an issue or request a feature
12+
13+
To report an issue or request a feature in TypedUnits, please first search the
14+
[issue tracker on GitHub](https://github.com/quantumlib/TypedUnits/issues) to
15+
check if there is already an open issue identical or similar to your bug
16+
report/feature request. If there is none, go ahead and file a new issue in the
17+
issue tracker.
18+
19+
## Contact the maintainers
20+
21+
For any questions or concerns not addressed here, please email
22+
[quantum-oss-maintainers@google.com](mailto:quantum-oss-maintainers@google.com).

0 commit comments

Comments
 (0)