In the spirit of Twelve-Factor Apps, this is a list of concrete things that you can do to make your software better. Some of it overlaps with Twelve-Factor Apps, but it's all good.
All of our apps will use git and Github for hosting repositories. This gives us a great collaboration and code review tool, an issue tracker, a wiki, and free static web hosting. All MoFactor apps should be owned by the Mozilla organzation
Unless we absolutely need to, everything with do on Github should be completely open and transparent. Examples of things that might need to be private include:
- Security bugs (file these on Bugzilla)
- Application configuration
- Service credentials
The README.md should answer common questions like:
- What does your software do? Is it an application? A library?
- Links through to important sections of the wiki. Like installation instructions
- How do I contribute code? Link to contributors file
- Where is the community around this software? List IRC channels, mailing lists, issue trackers, code repositories, etc.
The wiki should contain more complex instructions/documents that would otherwise clog up the README. WIKI's feel very 'MoFactor' to me and being a bit more fluid seem a better place for this kind if info.
- How do I install and run your software? What are the prerequisites? What operating systems does it run on?
- How do I change the configuration of your software? What is the API for your software? Provide examples, as well as a reference. For larger software packages, you may need to move this documentation somewhere else. If do you, then link to it from here.
Github will add a banner to the new pull request page when you add a file named "CONTRIBUTING" or "CONTRIBUTING.md" to your repository:
This contributors document should be the canonical place for answers to:
- What are some ways I can contribute?
- Where can I file bugs? What makes a good bug report?
- What do I need to do to contribute code? What will make my pull request immediately mergeable?
- What is the code review process?
- What sort of organizational schema is used for Github Issues? What labels are used, and what do they mean? How are milestones handled?
Rather than dictate a process that every MoFo project will follow, every MoFo project has a contribution process that exists in the contributors document.
Every project must have a license assigned to it, and the copyright for the project assigned to the Mozilla Foundation. If you're not sure what license you should be using, default to the Mozilla Public License v2.0. Other licenses that we currently use are:
- BSD 3-clause license
- BSD 2-clause license
- MIT license
If a MoFo project is using any other license, it is strongly suggested to switch to the MPL v2.0 if possible.
It's important to have a list of contributors to your project for two reasons:
- You need a list of people to contact if you need to change your license
- It's good to recognize people for their code contributions
Just put each contributors name and email in a CONTRIBUTORS document. Also humans.txt?
Github has a built-in service hook for IRC that sends a message to a channel of your choice when:
- Commits are pushed to a repo
- A pull request is opened
- Branches are created or deleted
- Builds break?
It's a great way to keep an eye on repository activity throughout the day.
Continuous integration can be used to automate tools such as:
- Linting
- Unit tests
- Style checking
- Builds
Travis CI is free, integrates with any language, and integrates status directly into each pull request. There is absolutely no reason to not use Travis CI.
A Procfile in the root of the repository enables deployment to Heroku. Any developer can run a application on Heroku for free, and the Foundation can use it for dev/staging/production environments.
In the event that Github goes down, it's always nice to have a backup so you can keep working. Fortunately, Mozilla already provides one for us: http://gitmirror.mozilla.org/. Mirror setup instructions are located at https://intranet.mozilla.org/Git.
- There has been no mention of tagging. But do we really need tags? A commit hash is unique, and if we want to get to the point where anyone can deploy, not tagging is one hurdle that wouldn't need to be crossed
- Date tagging vs semver tagging
- How do we do deployments?
- Should Heroku on prod be the gold standard we aim for?
- How do we deal with Heroku going down, can we do back-up deployments on Labs infrastructure?
- Packaging apps into .deb/.rpm?
- We should mention security reviews in here somewhere
Fork this document! Improve it!
I thought a standard set of tags would be beneficial in allowing ease of browsing of our issues by contributors. I did a bit of analysis, a bit of thinking and came up with these as a starting point for discussion - https://mofowebdev.etherpad.mozilla.org/github-webmaker-tags