sphinx-doc / sphinx-doc/sphinx

Improve `doc/internals/contributing.rst`

Open
#10,437 5 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

type:docs type:enhancement
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's A?) for backward-compatible changes, and master for incompatible/substantial changes. I want to submit a bug fix that, I think, should go on all active branches. Should I make the PR against 5.x (i.e. the highest "A")? Will it be back/forward-ported to 4.x/master? Is 4.x still 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't python3 -m venv .venv be better? (.venv is also already included in the .gitignore file). 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-xyz instead (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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.