Overhaul top-level README file and convert format to Markdown #6988

mhucka · 2025-01-28T00:33:09Z

This is a major overhaul of the main Cirq README file. Much of the
content is rewritten, and there are numerous additions and
enhancements all over. The changes include but are not limited to:

Updates and corrections
Addition of new sections
Centering and resizing the logo for a more professional look
Addition of GitHub badges for extra "pizzazz"
Addition of pointers to related Quantumlib software
Addition of a table of contents
Improvements to info about how to cite Cirq
Conversion to Markdown format to allow formatting that is
compatible with both GitHub and PyPI

This is a follow-on to now-closed PRs #6903 and #6901, which concerned
making roughly the same changes while keeping with the
reStructuredText format of the previous README file. Switching to
Markdown allows use of some simple raw HTML to achieving formatting
that is not possible in pure Markdown, and still do so in a way that
works on both GitHub and PyPI.

mhucka · 2025-01-28T00:42:11Z

Here are screenshots of what the new page will look like.

Light mode:

Dark mode:

codecov · 2025-01-28T00:45:37Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 97.89%. Comparing base (26b1f46) to head (14cb5db).
Report is 6 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6988   +/-   ##
=======================================
  Coverage   97.89%   97.89%           
=======================================
  Files        1085     1085           
  Lines       95131    95131           
=======================================
+ Hits        93124    93125    +1     
+ Misses       2007     2006    -1

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

mhucka · 2025-01-28T03:45:20Z

Note: the failing checks on Windows are due to the new README file triggering a bug in the dev_tools/ scripts: several of them call open() without checking the character encoding used in the file or providing an encoding parameter to the open() call. This can fail when a platform's default encoding does not match the encoding actually used in the file. In this case, the addition of a emoji character in UTF-8 in the new README.md is resulting in a failure on Windows, where I guess the default encoding is not assumed by Python to be UTF-8.

PR #6989 provides a fix to the underlying problem. Applying that PR should make the checks in this PR succeed.

mhucka · 2025-01-28T05:52:24Z

In the last commit (b93082b), I used Markdown reference links to try to make the source text more readable. If the result is not actually an improvement, then we can delete that commit.

README.md

pavoljuhas

LGTM with a couple of minor comments.
Thank you for improving this!

pavoljuhas

One extra thing before merge - please delete README.rst

mhucka · 2025-01-30T22:57:49Z

One extra thing before merge - please delete README.rst

Done in the latest commit.

This is a major overhaul of the main Cirq README file. Much of the content is rewritten, and there are numerous additions and enhancements all over. The changes include but are not limited to: - Updates and corrections - Addition of new sections - Centering and resizing the logo for a more professional look - Addition of GitHub badges for extra "pizzazz" - Addition of pointers to related Quantumlib software - Addition of a table of contents - Improvements to info about how to cite Cirq - Conversion to Markdown format to allow formatting that is compatible with both GitHub and PyPI This is a follow-on to now-closed PRs quantumlib#6903 and quantumlib#6901, which concerned making roughly the same changes while keeping with the reStructuredText format of the previous README file. Switching to Markdown allows use of some simple raw HTML to achieving formatting that is not possible in pure Markdown, and still do so in a way that works on both GitHub and PyPI.

No content edits (except possibly one or two trivial changes of wording). This changes some links to use Markdown "reference" link syntax, to make some of the source text more readable.

The previous links for the bibliographic records went to Cirq 1.2 in Zenodo. There doesn’t seem to be a way to get Zenodo to produce bibtex for the latest version of a record (only specific versions of a record), so I ended up using doi.org, but that one doesn't have a way to produce MarcXML. So I removed that format, leaving the other two. This also moves the GitHub contributors badge/count, per recommendation by Pavol in the review of this PR.

This is so that existing links go to same section despite the renamed heading.

pavoljuhas · 2025-01-31T00:38:57Z

Somehow this PR branch picked commits from the main -

$ git log --oneline main..f55479be --author="(Seneca|Doug|Pavol|Dax|Matthew)"
37cf3225 add snapshot_id to get_sampler interface on engine object (#7005)
0039d36f Streamline proto serialization of circuits with duplicate operations (#6991)
98314aae Fix check/nbformat installation and execution (#7004)
fdd87e7d Fix mapped measurement keys of repeat_until fields in CircuitOperations (#6881)
3f4945f9 Fix logic for handling `repetition_ids` in `CircuitOperation.replace` (#6984)

@mhucka - For the sake of better merge message - can you please reset it to rebased-6988 from my repo which drops those commits and has the same content?

git checkout mhucka-new-top-readme
git fetch https://github.com/pavoljuhas/Cirq.git rebased-6988
# last check - should have no output
git diff mhucka-new-top FETCH_HEAD


git reset FETCH_HEAD
git push --force-with-lease ...

mhucka · 2025-01-31T00:52:59Z

Oh, foo, how that did happen.

mhucka · 2025-01-31T19:36:13Z

Thanks for the clear instructions! I followed them and it looks like those extra commits are no longer here.

Somehow this PR branch picked commits from the main -

$ git log --oneline main..f55479be --author="(Seneca|Doug|Pavol|Dax|Matthew)"
37cf3225 add snapshot_id to get_sampler interface on engine object (#7005)
0039d36f Streamline proto serialization of circuits with duplicate operations (#6991)
98314aae Fix check/nbformat installation and execution (#7004)
fdd87e7d Fix mapped measurement keys of repeat_until fields in CircuitOperations (#6881)
3f4945f9 Fix logic for handling `repetition_ids` in `CircuitOperation.replace` (#6984)

@mhucka - For the sake of better merge message - can you please reset it to rebased-6988 from my repo which drops those commits and has the same content?

git checkout mhucka-new-top-readme
git fetch https://github.com/pavoljuhas/Cirq.git rebased-6988
# last check - should have no output
git diff mhucka-new-top FETCH_HEAD


git reset FETCH_HEAD
git push --force-with-lease ...

* Overhaul top-level README and convert to Markdown This is a major overhaul of the main Cirq README file. Much of the content is rewritten, and there are numerous additions and enhancements all over. The changes include but are not limited to: - Updates and corrections - Addition of new sections - Centering and resizing the logo for a more professional look - Addition of GitHub badges for extra "pizzazz" - Addition of pointers to related Quantumlib software - Addition of a table of contents - Improvements to info about how to cite Cirq - Conversion to Markdown format to allow formatting that is compatible with both GitHub and PyPI This is a follow-on to now-closed PRs quantumlib#6903 and quantumlib#6901, which concerned making roughly the same changes while keeping with the reStructuredText format of the previous README file. Switching to Markdown allows use of some simple raw HTML to achieving formatting that is not possible in pure Markdown, and still do so in a way that works on both GitHub and PyPI. * Adapt setup.py to work with new Markdown-format README * Update to reference README.md instead of README.rst * Use md reference links for better plain-text readability No content edits (except possibly one or two trivial changes of wording). This changes some links to use Markdown "reference" link syntax, to make some of the source text more readable. * Fix list indentation to follow Google Markdown style * Fix links to bib records & reposition recontributors number The previous links for the bibliographic records went to Cirq 1.2 in Zenodo. There doesn’t seem to be a way to get Zenodo to produce bibtex for the latest version of a record (only specific versions of a record), so I ended up using doi.org, but that one doesn't have a way to produce MarcXML. So I removed that format, leaving the other two. This also moves the GitHub contributors badge/count, per recommendation by Pavol in the review of this PR. * Remove README.rst * Add link target for #how-to-cite This is so that existing links go to same section despite the renamed heading.

CirqBot added the size: L 250< lines changed <1000 label Jan 28, 2025

mhucka marked this pull request as ready for review January 28, 2025 00:37

mhucka requested review from vtomole and a team as code owners January 28, 2025 00:37

mhucka requested a review from MichaelBroughton January 28, 2025 00:37

pavoljuhas reviewed Jan 29, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

pavoljuhas reviewed Jan 29, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

pavoljuhas approved these changes Jan 29, 2025

View reviewed changes

pavoljuhas requested changes Jan 29, 2025

View reviewed changes

mhucka self-assigned this Jan 30, 2025

mhucka enabled auto-merge January 30, 2025 22:57

mhucka force-pushed the mhucka-new-top-readme branch from 396ca1a to a1c1512 Compare January 30, 2025 23:19

mhucka requested review from mrwojtek, ma5x, pschindler, wcourtney and verult as code owners January 30, 2025 23:19

pavoljuhas approved these changes Jan 31, 2025

View reviewed changes

mhucka added this pull request to the merge queue Jan 31, 2025

mhucka added 6 commits January 30, 2025 16:24

Adapt setup.py to work with new Markdown-format README

07b4ce3

Update to reference README.md instead of README.rst

e1a8dce

Use md reference links for better plain-text readability

7bdf723

No content edits (except possibly one or two trivial changes of wording). This changes some links to use Markdown "reference" link syntax, to make some of the source text more readable.

Fix list indentation to follow Google Markdown style

f663d1f

mhucka added 2 commits January 30, 2025 16:24

Remove README.rst

b16f384

Add link target for #how-to-cite

964c6f7

This is so that existing links go to same section despite the renamed heading.

pavoljuhas removed this pull request from the merge queue due to a manual request Jan 31, 2025

mhucka force-pushed the mhucka-new-top-readme branch from 0f8bec3 to 964c6f7 Compare January 31, 2025 19:33

Merge branch 'main' into mhucka-new-top-readme

14cb5db

mhucka enabled auto-merge January 31, 2025 19:40

mhucka added this pull request to the merge queue Jan 31, 2025

Merged via the queue into quantumlib:main with commit d936ee3 Jan 31, 2025
38 checks passed

mhucka deleted the mhucka-new-top-readme branch January 31, 2025 19:59

mhucka added the area/docs label Feb 1, 2025

mhucka changed the title ~~Overhaul top-level README and convert to Markdown~~ Overhaul top-level README file and convert format to Markdown Apr 8, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Overhaul top-level README file and convert format to Markdown #6988

Overhaul top-level README file and convert format to Markdown #6988

Uh oh!

mhucka commented Jan 28, 2025

Uh oh!

mhucka commented Jan 28, 2025

Uh oh!

codecov bot commented Jan 28, 2025 •

edited

Loading

Uh oh!

mhucka commented Jan 28, 2025

Uh oh!

mhucka commented Jan 28, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

pavoljuhas left a comment

Uh oh!

pavoljuhas left a comment

Uh oh!

mhucka commented Jan 30, 2025

Uh oh!

Uh oh!

pavoljuhas commented Jan 31, 2025

Uh oh!

mhucka commented Jan 31, 2025

Uh oh!

mhucka commented Jan 31, 2025

Uh oh!

Uh oh!

Uh oh!

Overhaul top-level README file and convert format to Markdown #6988

Overhaul top-level README file and convert format to Markdown #6988

Uh oh!

Conversation

mhucka commented Jan 28, 2025

Uh oh!

mhucka commented Jan 28, 2025

Uh oh!

codecov bot commented Jan 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

mhucka commented Jan 28, 2025

Uh oh!

mhucka commented Jan 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pavoljuhas left a comment

Choose a reason for hiding this comment

Uh oh!

pavoljuhas left a comment

Choose a reason for hiding this comment

Uh oh!

mhucka commented Jan 30, 2025

Uh oh!

Uh oh!

pavoljuhas commented Jan 31, 2025

Uh oh!

mhucka commented Jan 31, 2025

Uh oh!

mhucka commented Jan 31, 2025

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Jan 28, 2025 •

edited

Loading

mhucka commented Jan 28, 2025 •

edited

Loading