Add recommended files for community support & update CONTRIBUTING.md #6898

mhucka · 2024-12-30T05:02:40Z

This adds two files recommended as best practices by GitHub:

SUPPORT.md
.github/SECURITY.md

This also adds a CITATION.cff, which GitHub uses to provide the info for the "Cite this software" button on the front page of the repository.

Finally, this also makes a number of updates and enhancements to the existing CONTRIBUTING.md file.

Per GitHub best practices, this give people instructions for reporting security vulnerabilities in this project.

SUPPORT.md files are another GitHub best practice; they're used to to let people know about ways to get help with a project.

[`CITATION.cff`](https://citation-file-format.github.io/) files are plain text files with human- and machine-readable citation information for software. Code developers can include them in their repositories to let others know how to correctly cite their software. GitHub supports them, and uses `CITATION.cff` files to automatically produce citation metadata records for the "Cite this repository" button on a repository's front page.

This contains a variety of small changes: - capitalization fixes (e.g., cirq → Cirq) - clarifications - links to more information

codecov · 2024-12-30T05:14:38Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 97.86%. Comparing base (dbada0e) to head (4fcfb22).
Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6898      +/-   ##
==========================================
- Coverage   97.87%   97.86%   -0.01%     
==========================================
  Files        1084     1084              
  Lines       94406    94406              
==========================================
- Hits        92396    92395       -1     
- Misses       2010     2011       +1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

pavoljuhas

LGTM with some minor suggestions, thank you for adding these!

Please see the comments before merging.

pavoljuhas · 2025-01-09T22:28:09Z

CITATION.cff

+version: 1.4.1
+date-released: 2024-06-26
+url: https://quantumai.google/cirq
+repository-code: https://github.com/quantumlib/cirq


nit -

Suggested change

repository-code: https://github.com/quantumlib/cirq

repository-code: https://github.com/quantumlib/Cirq

pavoljuhas · 2025-01-09T22:35:12Z

CONTRIBUTING.md

@@ -3,14 +3,16 @@
 We'd love to accept your patches and contributions to this project.
 We do have some guidelines to follow, covered in this document, but don't
 worry about (or expect to) get everything right the first time!
-Create a pull request and we'll nudge you in the right direction. Please also
+Create a [pull request](https://en.wikipedia.org/wiki/Fork_and_pull_model)


Do we need this wiki link here? The wiki article is very brief and not much clarifying for a novice GitHub user.

Fair point.

pavoljuhas · 2025-01-09T22:48:18Z

CONTRIBUTING.md

-```https://github.com/USERNAME/cirq``` where ```USERNAME``` is
-your github id. Use the directions on the
+The preferred manner for submitting pull requests is for developers to
+[fork](https://docs.github.com/articles/working-with-forks)


The fork link might be redundant here - the process is described step-by-step below.

pavoljuhas · 2025-01-09T22:49:42Z

CONTRIBUTING.md

+up a fork is as follows:
+
+1. Fork the Cirq repository (you can use the _Fork_ button in upper right
+corner of the [repo home page](https://github.com/quantumlib/Cirq)).


nit -

Suggested change

corner of the [repo home page](https://github.com/quantumlib/Cirq)).

corner of the [repository page](https://github.com/quantumlib/Cirq)).

pavoljuhas · 2025-01-09T22:52:44Z

CONTRIBUTING.md

+1. Fork the Cirq repository (you can use the _Fork_ button in upper right
+corner of the [repo home page](https://github.com/quantumlib/Cirq)).
+Forking creates a new GitHub repo at the location
+`https://github.com/USERNAME/cirq`, where `USERNAME` is


Nit - let us fix also other instances of cirq --> Cirq capitalization in URLs here

Suggested change

`https://github.com/USERNAME/cirq`, where `USERNAME` is

`https://github.com/USERNAME/Cirq`, where `USERNAME` is

pavoljuhas · 2025-01-09T22:54:47Z

CONTRIBUTING.md

-main cirq repo you may need to merge in changes.  To do this,
-first update your local main and then merge the local main
+1. If your local copy has drifted out of sync with the `main` branch of the
+the main Cirq repo, you may need to merge in the latest changes.  To do this,


typo - de duplicate

Suggested change

the main Cirq repo, you may need to merge in the latest changes. To do this,

main Cirq repo, you may need to merge in the latest changes. To do this,

Good catch.

pavoljuhas · 2025-01-09T22:57:38Z

CONTRIBUTING.md

+    You may need to fix [merge
+    conflicts](https://docs.github.com/articles/about-merge-conflicts)


nit - readability as plain text

Suggested change

You may need to fix [merge

conflicts](https://docs.github.com/articles/about-merge-conflicts)

You may need to fix [merge conflicts](

https://docs.github.com/articles/about-merge-conflicts)

pavoljuhas · 2025-01-09T23:02:06Z

CONTRIBUTING.md

-1. Now when you navigate to the cirq page on github,
-[https://github.com/quantumlib/cirq](https://github.com/quantumlib/cirq)
+1. Now when you navigate to the Cirq repository on GitHub
+([https://github.com/quantumlib/cirq](https://github.com/quantumlib/cirq)),


no need for expanded [TEXT](URL) syntax here -

Suggested change

([https://github.com/quantumlib/cirq](https://github.com/quantumlib/cirq)),

(https://github.com/quantumlib/Cirq),

Since you are at it, can you please also remove the redundant <> in the CLA link here -

Cirq/CONTRIBUTING.md

Line 17 in 1e4e2a7

part of the project. Head over to <https://cla.developers.google.com/> to see

pavoljuhas · 2025-01-09T23:08:06Z

CONTRIBUTING.md

-When type checking produces a false positive, it can be ignored with
-annotations like `# type: ignore`.
+When type checking produces a false positive, it can be silenced with
+annotations such like `# type: ignore`.


nit -

Suggested change

annotations such like `# type: ignore`.

annotations such as `# type: ignore`.

pavoljuhas · 2025-01-09T23:12:12Z

CONTRIBUTING.md

 [development page](docs/dev/development.md) on how to run the continuous
 integration checks locally.

-Please be aware of the following code standards that will be applied to any
+Please be aware of the following coding standards that will be applied to any


Can you please remove the /en/latest suffix from the pytest and pytest-cov URLs below?
Their top pages already redirect to .../en/latest and are less likely to become invalid.

These happen when I copy-paste the links. You’re right that they should be removed. This is something we should put into linter rules.

Correction to capitalization.

mhucka added 4 commits December 29, 2024 20:55

Add ./github/SECURITY.md

5cb5c18

Per GitHub best practices, this give people instructions for reporting security vulnerabilities in this project.

Add SUPPORT.md file

c1e3b66

SUPPORT.md files are another GitHub best practice; they're used to to let people know about ways to get help with a project.

Make small corrections & enhancements to CONTRIBUTING.md

5469c8b

This contains a variety of small changes: - capitalization fixes (e.g., cirq → Cirq) - clarifications - links to more information

CirqBot added the size: M 50< lines changed <250 label Dec 30, 2024

mhucka marked this pull request as ready for review December 30, 2024 05:17

mhucka requested review from vtomole and a team as code owners December 30, 2024 05:17

mhucka requested a review from dstrain115 December 30, 2024 05:17

mhucka added the area/docs label Dec 31, 2024

mhucka self-assigned this Dec 31, 2024

Merge branch 'main' into mhucka-add-recommended-files

94de29a

mhucka requested a review from pavoljuhas January 7, 2025 16:51

Merge branch 'main' into mhucka-add-recommended-files

1e4e2a7

pavoljuhas approved these changes Jan 9, 2025

View reviewed changes

mhucka and others added 3 commits January 10, 2025 11:35

Update CITATION.cff

d7c271d

Correction to capitalization.

Fixes for CONTRIBUTING.md issues raised during code review

2621dec

Merge branch 'main' into mhucka-add-recommended-files

4fcfb22

mhucka enabled auto-merge (squash) January 10, 2025 20:06

mhucka merged commit 5d317ba into quantumlib:main Jan 10, 2025
35 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add recommended files for community support & update CONTRIBUTING.md #6898

Add recommended files for community support & update CONTRIBUTING.md #6898

mhucka commented Dec 30, 2024

codecov bot commented Dec 30, 2024 •

edited

Loading

pavoljuhas left a comment

pavoljuhas Jan 9, 2025

pavoljuhas Jan 9, 2025

mhucka Jan 10, 2025

pavoljuhas Jan 9, 2025

pavoljuhas Jan 9, 2025

pavoljuhas Jan 9, 2025

pavoljuhas Jan 9, 2025

mhucka Jan 10, 2025

pavoljuhas Jan 9, 2025

pavoljuhas Jan 9, 2025

pavoljuhas Jan 9, 2025

pavoljuhas Jan 9, 2025

mhucka Jan 10, 2025

	repository-code: https://github.com/quantumlib/cirq
	repository-code: https://github.com/quantumlib/Cirq

	corner of the [repo home page](https://github.com/quantumlib/Cirq)).
	corner of the [repository page](https://github.com/quantumlib/Cirq)).

	`https://github.com/USERNAME/cirq`, where `USERNAME` is
	`https://github.com/USERNAME/Cirq`, where `USERNAME` is

	the main Cirq repo, you may need to merge in the latest changes. To do this,
	main Cirq repo, you may need to merge in the latest changes. To do this,

		You may need to fix [merge
		conflicts](https://docs.github.com/articles/about-merge-conflicts)

	([https://github.com/quantumlib/cirq](https://github.com/quantumlib/cirq)),
	(https://github.com/quantumlib/Cirq),

	annotations such like `# type: ignore`.
	annotations such as `# type: ignore`.

Add recommended files for community support & update CONTRIBUTING.md #6898

Add recommended files for community support & update CONTRIBUTING.md #6898

Conversation

mhucka commented Dec 30, 2024

codecov bot commented Dec 30, 2024 • edited Loading

Codecov Report

pavoljuhas left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Dec 30, 2024 •

edited

Loading