Page MenuHomePhabricator

Add CONTRIBUTING.md to all reading web repositories
Closed, DeclinedPublic

Description

Getting started

  • 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.

Scope

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
  • MobileFrontend
  • Minerva

Event Timeline

jhobs renamed this task from [EPIC] Update documentation across Reading-Web extensions to [EPIC] Update documentation across Reading Web extensions.Aug 18 2016, 4:12 PM
Jhernandez moved this task from Incoming to Epics/Goals on the Web-Team-Backlog board.
Jdlrobson added a subscriber: Jdlrobson.

I'm not sure what to do with this task. I need to review the subtasks but I don't think its helpful categorising this as an epic.

I'm not sure what to do with this task. I need to review the subtasks but I don't think its helpful categorising this as an epic.

Why not?

Jdlrobson renamed this task from [EPIC] Update documentation across Reading Web extensions to Improve getting started documentation for new volunteers.Apr 18 2017, 9:27 PM
Jdlrobson removed a project: Epic.
Jdlrobson updated the task description. (Show Details)

I'm not sure what to do with this task. I need to review the subtasks but I don't think its helpful categorising this as an epic.

Why not?

Okay so I had time to reflect on this. This isn't really an epic in my opinion. There are some clear actionables here that with timeboxing can be resolved quite quickly. An epic in my head is something that should take an entire quarter/year. This is just a big task. We can of course subtask this if any when we commit to working on it.

I don't see the need for a generic documentation epic. We have a documentation tag already to help us group documentation related tasks. I've added a documentation tag to the left menu to help us group and identify documentation tasks.

^ Other popular projects have CONTRIBUTING.md in their root directory.

Jdlrobson lowered the priority of this task from Medium to Low.Aug 22 2017, 7:05 PM

Not really clear what the goal is here and for what.

Jdlrobson renamed this task from Improve getting started documentation for new volunteers to Add CONTRIBUTING.md to all reading web repositories.Feb 14 2018, 7:37 PM
Jdlrobson raised the priority of this task from Low to Medium.
Jdlrobson updated the task description. (Show Details)

We pointed out page previews has a good contributory instructions in its README.md

We plan to rewrite MobileFrontend's JS and document that better in the process so doing anything related to that now would be counter-productive.

Selenium is well documented now thanks to the efforts of release engineering while porting to Node.