Skip to content

feat: Add references page to handbook - #2073

Open
jstoobysmith wants to merge 1 commit into
leanprover-community:masterfrom
jstoobysmith:handbook-references
Open

jstoobysmith wants to merge 1 commit into
leanprover-community:masterfrom
jstoobysmith:handbook-references

Conversation

@jstoobysmith

Copy link
Copy Markdown
Member

Added a references page to the contribution handbook made with the help of AI, but all of the ideas were my own, and this is basically a transcription of those.

@github-actions github-actions Bot added the small label Nov 13, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Thank you for this pull-request (PR). If this is your first PR, welcome to the community!

While you wait for a review, note that you can review PRs too; reviewing is not restricted to maintainers. Our review guidelines explain what to look for.

Over time, contributions such as reviews, maintenance and documentation are recorded on contributions.physlib.io.

Three main points:

  • Comment -awaiting-author on its own line to remove that label from your PR.
  • Comment blocked-by-PR or -blocked-by-PR on its own line to add or remove that label, respectively.
  • The first review might take several days to arrive. If in doubt message on the Zulip.

For the author: Please read

Below is what will happen next. Please read carefully if you are not familiar with the process. You may open other PRs while this one is being reviewed, and can stack PRs on top of each other, so don't let these steps slow you down.

  1. Some automated checks will be run on your PR. You can see the results of these checks at the buttom of your PR page. If any of these checks fail, you will need to fix the issues before your PR can be merged. You can learn more about these here, including how to run them locally, which is sometimes quicker than relying on the GitHub Actions. If you have never had a PR merged before, you may have to wait for a reviewer to manually start these checks (this is for security).

  2. A reviewer will look at your PR and may ask you to make changes. This may happen a couple of days after you submit your PR, so you may need to be patient. But it should not be longer than that - if it is please bring it to the attention of the community on the Zulip. The level of review will depend on where your PR is submitted. If it is submitted to ./Physlib or ./QuantumInfo, the review will be more thorough than if it is submitted to ./PhyslibAlpha. You can find out more about what the review process is looking for in our review guidelines. If a reviewer adds an awaiting-author label to your PR, address the review comments, then please remove that label by adding a comment with -awaiting-author. This helps us keep track of reviews.

  3. The reviewer will either approve your PR, or request more changes (in which case we return to step 2). Once your PR is approved, it will be merged by a maintainer, this should happen shortly after approval, though you may get more comments at this stage.

Tip: The easiest way to get a fast review is to submit a PR that is small and self-contained, and has clear documentation explaining why things are the way they are in your changes.

If you have any problems or questions, please reach out to the community on the Zulip.

For reviewers: Summary of your PR

Found differences:
@@ docs/ContributionHandbook/References.md @@
+ file added docs/ContributionHandbook/References.md (+45 -0)
1 difference

The declarations are found by reading the diff as text, without regard for namespaces, so a declaration whose keyword and name are on different lines is missed, and two declarations of the same name in different namespaces are listed as one. A change to a proof, or to the body of a definition, does not appear. See scripts/alpha/github/pr_summary.lean.

Summary of commit fd1e02b, remade whenever a commit is pushed.

@jstoobysmith
jstoobysmith requested a review from zhikaip November 16, 2026 06:44

## 3. Include exact quotes

Where possible, include an exact quote from the source in the references section. Quotes can be checked in both directions: a reader can check that the quote describes the physics being formalized, and that the quote actually appears in the source. Quotes can be left out when citing an overview article.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not so sure about this, there are often subtle differences between the informal statement and the formalisation, and also building up an API may not necessary have a headline statement that this may be applicable


## 5. Link to the exact page

When you cite a specific part of a paper, the link in the references section should go to the page where that part appears. On arXiv, for example, you can link directly to a given page of a paper.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in relation to the comment on point 3, I think this is already sufficient.


## 4. Prefer open-access sources

Prefer open-access sources, and include a link. Physlib is an open-source project, and it is very hard to check that a reference is correct if the source is closed access. This is a soft rule: at some point you will need to refer to the standard literature, such as Landau and Lifshitz.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is not wrong, but this may give the wrong impression that formalisation has to follow a source faithfully, but in practice it might be actually desirable to come up with a better generalisation/implementation which could take inspiration from more than one source, or even a novel framework, and I think we should encourage creativity (given the contributor knows what they're doing of course).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants