sphinx-doc / sphinx-doc/sphinx
Improve `doc/internals/contributing.rst`
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Is your feature request related to a problem? Please describe.
I followed the Contributing to Sphinx docs and some parts were not clear enough and could be improved.
Describe the solution you'd like
The following parts of the Getting started section should be improved/updated.
- "4.Checkout the appropriate branch." is not too clear. It says to use
A.x(what'sA?) for backward-compatible changes, andmasterfor incompatible/substantial changes. I want to submit a bug fix that, I think, should go on all active branches. Should I make the PR against5.x(i.e. the highest "A")? Will it be back/forward-ported to4.x/master? Is4.xstill receiving bug fixes? There is also a link to the Sphinx’s release process, but it's in a sentence about "urgent release", so it doesn't seem related. - "5. Setup a virtual environment." recommends to use
virtualenv ~/.venv-- wouldn'tpython3 -m venv .venvbe better? (.venvis also already included in the.gitignorefile). The description is also not particularly clear: should I created it if I want to be able to run tests without making global changes to my environment (including installing dependencies)? - "6. Create a new working branch." could recommend the more modern alternative
git switch -c feature-xyzinstead (or in addition, for backward compatibility) to the old one. - "7. Hack, hack, hack." recommends to start hacking, but I think it would make sense to run the tests first to see if they pass before breaking them.
- "8. Add a bullet point to CHANGES ..." should link to the file (and/or say "to the CHANGES file"). This section also suggests to add an issue number to the commit message. Should an issue always be created before a PR? Should I mention the issue number in all commits I do in the branch?
The Unit tests section seems to assume that I have tox installed and lists several commands to test in specific scenarios. What's the simplest set of commands needed to install the necessary dependencies in a venv and run all tests? Do I need tox or is pytest enough? How do I install/run it?
Eventually I was able to figure out most of the answers, but it would be better if they were documented clearly.
Describe alternatives you've considered
Giving up contributing to Sphinx or submitting an incomplete PR without tests 🙃
Additional context
I wanted to fix an issue I found, and I was following the docs in order to create a PR.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with doc/internals/contributing.rst, especially the Getting started and Unit tests sections. Review the existing branch, virtual-environment, Git, and test instructions, then update the documented workflow and commands so a contributor can create an environment and run the tests. Done means the referenced steps and files are clear and current.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100