Common-voice: Collect and document contribution guidelines

[nevik]

_EDIT: This issue has been broadened in scope to discuss the introduction of contribution guidelines in general. Initially it talked specifically about the Node and npm versions used for the project.
The original content remains at the end of this post._

---

_Original text:_

From the presence of a package-lock.json file in the repo, I presume that at least npm v5 (and therefore, probably Node v8) is needed.

To make it less of a trial & error for new contributors when setting up their dev environment, could you add some info on actual minimum required versions for these pre-npm install tools to the README? :)

Or just reply here and i'll create a pull request ;)

[kenrick95]

Though I locally run this project in Node 8 (and npm v5), I see that .travis.yml specifies Node v7 (and in the builds, it installs npm v4).

Yeah, I agree that we should specify recommended Node & npm version to run this project on.

[Omniscimus]

I agree, and some information about how the project modules work and what frameworks are being used would be helpful as well. Such as, for the web server we're using node, preact, typescript, whatever (with links to documentation). Could be in the readme, or in a separate contributors file.

[mikehenrty]

This is a great start for working towards a contributors file!

Some sections I think we would need are:

• Pre-reqs: node v7 or higher and npm 4 or higher (or do you all think we should require v8/v5?
• Setting up Dev Environment: we can move the stuff in the README here
• How to run and test
• Choosing a good first bug (link to help wanted list)
• Explanation of important tools: gulp, preact, typescript, postcss, (anything else?)
• File structure: we can move this from the README too

What else?

Note, @nevik has some great ideas here too: https://discourse.mozilla.org/t/contributing/17295/5

[nevik]

For convenience, I'm cross-posting my ideas here :)

---

I was thinking something along what other OSS projects use, and what GitHub recommends to be in a CONTRIBUTING file.

Some of the points I think would be great to mention there:

• points and methods of communicating with the team/maintainers
  
  
  
  • e.g. GH issues for bug reports/feature requests, Discourse for more general discussion, whatever real-time chat avenue comes out of our other conversation
  
  
• more details on setting up the local development environment
  
  
  
  • list of software required (e.g. MySQL isn't currently mentioned anywhere)
  
  
  • versions required (esp. Node and npm, see #423)
  
  
  • where configuration goes, and what needs to be configured to get up and running; possibly also where to get backend/DB and AWS credentials (see also: #427)
  
  
  • some of these technical details could also be extracted to another file (main README or a readme in another folder, or another file entirely), and referenced from CONTRIBUTING
  
  
• where to start in terms of things to change/fix/add
  
  
  
  • filter for "help wanted" issues on GH
  
  
  • ignore the "triage" tag (or not? otherwise indicate how you use and interpret the triage tag, and how this affects "ready for development)
  
  

[iveskins]

this is important info! https://github.com/mozilla/voice-web/pull/90
One needs to go to aws IAM console make a new access token and put the credentials in
~/.aws/credentials

and also install ffmpeg
and also if not hosting on local host maybe a webserver, and then also a https cert because otherwise browsers wont let the mic record.

also for the voting to work you needs a policy like below on your s3 bucket to allow access to the recorded files.

{
  "Version":"2012-10-17",
  "Statement":[
    {
      "Sid":"AddPerm",
      "Effect":"Allow",
      "Principal": "*",
      "Action":["s3:GetObject"],
      "Resource":["arn:aws:s3:::examplebucket/*"]
    }
  ]
}

[mikehenrty]

Note that @carolstran is working on a first version of this in #480.

[mikehenrty]

Thanks to @carolstran, we've got a great starting point from #427!! \o/ Let's continue to use this bug to talk about what we still need.

[carolstran]

Hey @mikehenrty, I'd love to add an explanation of issue labels to the contributing guides. So far I've noticed these ones:

help wanted
Triage (? A previous comment here suggested "indicating how you use and interpret the triage tag, and how this affects ready for development", but I'm not sure what that means)

2: non-technical (why the 2?)

OS: Windows
OS: Android
OS: iOS
Browser: Focus
App: iOS

Type: Enhancement
Type: Investigate
Type: Question
Type: Bug
(if any of these are different than what I could assume, let me know)

Priority: P1
Priority: P2
(who sets these? ^^ what is the difference?)

Am I missing any?

[mikehenrty]

@carolstran thanks for improving this even more!

For a full list, you can check out:
https://github.com/mozilla/voice-web/labels

In general I bet your intuition will be right. If you submit an initial PR, I can fix up any things needed.

P1: These are bugs that the community has deemed important by giving it 5 or more likes.

I removed P2 since we we're really using it.

[mikehenrty]

I think we have a pretty good start for this guide now. I'm going to close this, and let's open new issues for improvements we want to make to the guides.