Page MenuHomePhabricator

Improve documentation for getting started developing Toolhub
Closed, ResolvedPublic

Description

@bd808 wrote a tiny amount of documentation at https://gerrit.wikimedia.org/r/plugins/gitiles/wikimedia/toolhub/+/refs/heads/main/docs/CONTRIBUTING.rst but we can and should do better.

Both @Raymond_Ndibe and @Slst2020 are on boarding to the project with the insider advantage of being able to poke @bd808 with questions whenever they want. It seems like a good idea to take advantage of their new eyes and new questions to build out better documentation (and fix anything that seems harder than it should be) in the process of getting Toolhub running in local development mode for developing and testing features and bug fixes.

Event Timeline

bd808 renamed this task from Improve docuemenation for getting started developing Toolhub to Improve documentation for getting started developing Toolhub.Nov 16 2021, 12:37 AM
bd808 assigned this task to Slst2020.
bd808 triaged this task as Medium priority.
bd808 updated Other Assignee, added: Raymond_Ndibe.

https://wikitech.wikimedia.org/wiki/Toolhub.wikimedia.org#Local_development might be a good place to start building better docs. We can decide later if we would really like to move this documentation to metawiki or put it into the git repo directly.

@Raymond_Ndibe may already have some local notes, or at least fresh memories, to help start the improvements. I set @Slst2020 as the assignee for the task, but all of us should collaborate on the process.

I had no problems setting up my dev environment following CONTRIBUTING.rst using Mac with Docker for Desktop.

Some thoughts –

  • It could be helpful to have a section about style expectations, including which linters and formatters to run, how to run them separately on individual files, and where their respective configuration settings live
  • Idem for tests, a section about how to run tests and test coverage checks outside of the make test pipeline
  • It may be worth pointing out that docker-compose is already included with Docker for Desktop (relevant for Mac & Windows users)

@Raymond_Ndibe – please feel free to chime in with your own experience on getting things set up and what improvements you would like to see.

Change 742464 had a related patch set uploaded (by Slavina Stefanova; author: Slavina Stefanova):

[wikimedia/toolhub@main] docs: Improve documentation for getting started developing Toolhub

https://gerrit.wikimedia.org/r/742464

Change 742464 merged by jenkins-bot:

[wikimedia/toolhub@main] docs: Improve documentation for getting started developing Toolhub

https://gerrit.wikimedia.org/r/742464

Change 749220 had a related patch set uploaded (by BryanDavis; author: Bryan Davis):

[operations/deployment-charts@master] toolhub: Bump container version to 2021-12-20-122341-production

https://gerrit.wikimedia.org/r/749220

Change 749220 merged by jenkins-bot:

[operations/deployment-charts@master] toolhub: Bump container version to 2021-12-23-121200-production

https://gerrit.wikimedia.org/r/749220