Documenting minimizing diffs for ease of review
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 2.1k
- Forks
- 1k
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 12
Description
Suppose we have some lines that are close to 80 chars long
first text ... end first text.
second text ... end second text.
third text ... end third text.
and if the first line needs some sort of modification that would push it past 80 chars, we can either restructure the entire paragraph of raw rst so it looks tidier, but resulting in 4 lines of git diffs
first text plus some more ...
end first text. second text ...
end second text. third text ...
end third text.
or diffs can be minimized (but with an 'uglier' raw rst), such as like
first text plus some more ...
... end first text.
second text ... end second text.
third text ... end third text.
I think that for ease of reviewing, as well as to maintain a more useful git history, that the second is preferred in general but I haven't found it in the style guide, so maybe it can be added there if there's consensus on it?
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
Read the documentation style guide linked in the issue and review the existing discussion about minimizing diffs. Add guidance only if the project agrees on the preference, with examples showing the recommended wrapping style; the style guide should clearly document the convention when done.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100