docs: add contributing guide and issue/PR templates - #499
Merged
Conversation
lkdvos
force-pushed
the
docs/contributing
branch
from
August 3, 2026 23:16
e5339d3 to
cb61f2a
Compare
Contributor
|
After the build completes, the updated documentation will be available here |
Codecov Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
borisdevos
reviewed
Aug 4, 2026
borisdevos
left a comment
borisdevos
left a comment
Member
There was a problem hiding this comment.
Thanks for splitting up the big PR into pieces, this makes it easier to provide reviews :)
I just have a question about some of the markdowns here. I don't understand why some of them exist, in particular the 3 under the .github/ISSUE_TEMPLATE made here, as well as CONTRIBUTING.md under docs. Basically, any of the markdowns which aren't directly being displayed as a page in the docs, what are they for?
lkdvos
force-pushed
the
docs/contributing
branch
from
August 4, 2026 19:59
cb61f2a to
99ceab1
Compare
lkdvos
marked this pull request as ready for review
August 4, 2026 22:44
Member
Author
|
Most of these markdown files are actually just github-specific templates, that will open when you click the issues/pull requests pages. I'm not sure if it really matters all that much, and I don't particularly like these myself, but at least it is some place to invite people to contribute as well as give some guidelines on including versions and stacktraces? |
borisdevos
approved these changes
Aug 5, 2026
borisdevos
left a comment
borisdevos
left a comment
Member
There was a problem hiding this comment.
Small nitpicks, but otherwise good for me!
`CONTRIBUTING.md` is the canonical guide, rendered as a page through the thin `docs/src/contributing.md` include so it is reachable from the site as well as from GitHub. Issue templates split bug reports from questions, since the two need very different information, and the PR template asks for the things review kept having to ask for. Also refreshes `README.md` with a short positioning statement, brings `CITATION.cff` up to the v0.13.13 release, and records in the docstring style guide that unverified physics claims get a REVIEW marker for the maintainer. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> update contributing.md simplify readme
`docs/src/contributing.md` had been added as a hand-written second copy rather than the thin include it was described as, and the two had already drifted: the root file was missing the Discussions link and the development setup, the docs page was missing the AI-tooling policy and the selective-test invocations, while claiming the root file was authoritative. Keep `CONTRIBUTING.md` as the single source, since the repository root is where GitHub looks when it links contributing guidelines from the issue and pull request forms, and generate the manual page from it in `make.jl` with an `EditURL` pointing back at the real file. Along the way: the `!!! hint` admonition never rendered, as that file is read on GitHub rather than through Documenter, and the `dev --local MPSKit` it suggested does not check out `main` but clones into `./dev/`. Replaced with a Development setup section. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
TensorKit provides the tensors every algorithm here runs on, and its `CITATION.cff` declares a `preferred-citation`, so the entry points at the paper (arXiv:2508.10076) rather than the software DOI. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Adds a `references:` entry to `CITATION.cff` so citation tooling picks the dependency up rather than only human readers of the README, and a "Citing MPSKit" section on the references page with both works as proper bibliography entries. The TensorKit entry is the paper its own `CITATION.cff` marks as `preferred-citation` (arXiv:2508.10076), not the software DOI. Both bib entries use `@misc` rather than the biblatex-only `@software`, since the bibliography is parsed as BibTeX. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The contributing guide and README both send open-ended discussion to GitHub Discussions, but the issue chooser did not offer it, so that pointer only reached people who read CONTRIBUTING first. An `ISSUE_TEMPLATE/config.yml` surfaces it at the point where someone is about to file, alongside a link to the manual. The link is named for open-ended discussion rather than questions, to keep the split the Question template already makes. Blank issues stay enabled. The changelog checkbox in the pull request template was unconditional while the guide asks for an entry only on user-facing changes, so a docs-only PR could not tick it honestly. Now conditional, with the same wording as the guide. The home page table of contents listed only the manual pages, leaving the contributing guide and the new citation section unreachable from it. Extended to the rest of the site, mirroring the structure of `pages` in `make.jl`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Making `CONTRIBUTING.md` the rendered contributing page brought its `### Changelog` subsection into `docs/src/`, where it collides with the `# Changelog` heading of `changelog.md`. That was latent until the home page table of contents added a `[Changelog](@ref)`, at which point Documenter could no longer resolve the slug and the build failed at `[:cross_references]`. Renamed the subsection to `### Changelog entries`, rather than anchoring `changelog.md` with an `@id`: that file is read on GitHub by the contributors it is written for, and `# [Changelog](@id changelog)` renders there as a broken link. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Boris De Vos <143942306+borisdevos@users.noreply.github.com>
lkdvos
force-pushed
the
docs/contributing
branch
from
August 5, 2026 13:24
985d8af to
a0d4c3c
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Split out of #449 so it can be reviewed on its own; independent of the documentation content.
CONTRIBUTING.mdis the canonical guide, rendered as a page through the thindocs/src/contributing.mdinclude so it is reachable from the site as well as from GitHub. Issue templates split bug reports from questions, since the two need very different information, and the PR template asks for the things review kept having to ask for.Also refreshes
README.mdwith a short positioning statement, bringsCITATION.cffup to the v0.13.13 release, and records in the docstring style guide that unverified physics claims get a REVIEW marker for the maintainer.🤖 Generated with Claude Code