- remove the manual setup guide since we do not want to promote (and maintain) this approach any more,
- few rewordings in getting-started.rst iteself
- in the developer-setup guide:
- rewordings
- copy the 'install depencencies' from the manual-setup guide,
- add the missing step bin/update
- remove the docker setup part (been integrated in the swh-docker-dev's README)
- add a section on unit tests
Details
Details
- Reviewers
zack - Commits
- rDDOC9542708dd478: Refactor the getting started guides
Diff Detail
Diff Detail
- Repository
- rDDOC Development documentation
- Lint
Automatic diff as part of commit; lint not applicable. - Unit
Automatic diff as part of commit; unit tests not applicable.
Event Timeline
Comment Actions
Some light copy editing; This looks fine to me, but I'll leave the final review to @zack
| docs/developer-setup.rst | ||
|---|---|---|
| 10–12 | virtual env -> virtualenv | |
| 28 | *cringe* (I don't have anything better to offer) | |
| 29 | sudo wget https://www.postgresql.org/media/keys/ACCC4CF8.asc -O /etc/apt/trusted.gpg.d/postgresql.asc | |
| 82 | dependencies | |
| 83 | s/this // | |
| 106 | Maybe use prose rather than parenthetical? | |
| 167 | s/setup/server properly configured/ | |
| 168 | s/pifpaf_/&, which will spawn a temporary instance of postgresql, / | |
Comment Actions
Great, thanks for this doc refactoring!
I've noted a single minor point to be changed in the review above, and I've a naming change suggestion.
getting-started.rst is really not about getting started (with development) any more, it's really a "run Software Heritage locally" guide, as per title in the doc. Since that is a mouthful, I propose to rename that document "local-deployment.rst".
The other document sounds great.
Due to that, probably some changes in the index.rst describing the two documents are also needed (and probably developer-setup.rst should come first, given this is developer documentation). If you want to integrate these changes in this diff, great; if not, I'll propose those as separate changes later, once this is merged.
| docs/developer-setup.rst | ||
|---|---|---|
| 36–42 | Does having a running local postgres get in the way of unit testing? If not (as I suppose), I propose to just remove this Note. IMHO it's in the camp of "basic development machine administration" and it increase the length/complexity of the guide. If there's no harm in having postgres running, we should just leave it be. | |