- We don't really document our process for making contributions very well. We have sections in README.md that explain tests and commits, but some aren't especially well-written. As an example, I tried following the instructions for running tests and was immediately met with an error and nowhere to go for troubleshooting (if I were a first-time volunteer who didn't know about #wikimedia-mobile on IRC). In order to help onboard new devs and encourage volunteer contributions, I think we should refactor the top of README.md to be a bit more "how-to", or have another document in the repo to describe how to get started. If we decide on a new document I'd recommend CONTRIBUTING.md or CONTRIBUTING.mediawiki, the latter of which could correspond to a page on mediawiki.org.
- Add CONTRIBUTING.md
- Move anything developer specific to CONTRIBUTING.md. README.md should be for sysadmins. At the top of the README add a line "For those interested in contributing to the codebase please see CONTRIBUTING.md
- Review and update setup instructions in the new CONTRIBUTING.md file
- Add instructions that help a new contributor with only a fresh vagrant instance and Gerrit account to drive a change from start to finish, including running tests.
- As a contributor, if I'm not sure of how to properly document a method (syntax, format, etc.), my only real option is to open similar files and hope they have the info I need. For example, I've never known what @ignore does and can only assume it forces the linter to skip the method or something, which is odd as I've seen it on multiple important methods. For me, the answer is as simple as "ask a team member," but volunteers would be much more lost. We should more easily expose documentation -- be it links to official websites or our own documentation -- for libraries, testing frameworks, linters, and any other tools we use. Another example of this is our Selenium tests. We use a custom mediawiki implementation of Selenium, which is already not the most well-known framework. Googling for answers when writing a browser test for our extensions hardly provides useful info and will often just lead people to forego writing tests altogether.
- Link to suitable documentation for jsduck and Selenium in getting started instructions. Use relevant mediawiki.org wiki pages where possible.
The file does not need to be complete, but should give some basic instructions of how to get started in our codebase - running tests; where code/tests live. It should be applied to the following extensions. It doesn't need to be perfect. I'd suggest spending 2hrs at most writing one.
It should apply to the following code bases where we most frequently get contributions:
- Page previews