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.
- Stable - something like popcorn.webmaker.org this is a high-end, high traffic site and is built to ensure that it can cope with both fast feature iteration and high peaks in traffic.
- Immature - something like source.mozillaopennews.org this is a site in production but development is less regular and traffic less heavy. However if things do need to move quickly, or if we're especting a planned peak in traffic the app can still cope.
- Prototype - as the name suggests, a prototype! Incredibly useful for demo'ing ideas and concepts but with a limited shelf life and no expectation to handle mass traffic.
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 and system configuration
- Service credentials, api keys
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.
Outlined in https://gist.github.com/6a2cb8171b6411c7d9b4 this will ensure understanding of each projects state at an internal team level but also allow for ease of contribution by making the types of issue, their importance and their state in the code review process up front and in an understandable manner.
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.
While all code has commit hashes, named tags are very useful for tracking code base versions, as well as allowing automatic testing and deployment based on new versions. Tags are generated using the command:
git tag -a "tag name" -m "descriptive message"
Tags are pushed to the repo similar to normal branches, using the tag name:
git push repo "tag name"
The choice of exactly how to name a tag depends on the project needs, but it is strongly recommended that tags are named either by date of release or by Semantic version.
Annotated tags in git will be the starting point for all deployments on MoFactored apps. Dependent on the flavour of application this will trigger a different process.
This tag will be built into a deployable debian package, using the tag as the version, stored in the appropriate staging/prod apt repository, and deployed using puppet or AMI imaging into the live infrastructure. Thus, this tag should properly increment, causing puppet to see a new deployable version. Deployments are handled exclusively by DevOps for this type of application, and will involve security review, DevOps QA, and product team QA in a like-live environment. Deployment reports are generated for each new version, complete with git diffs and change reports from New Relic.
This tag can be used in the same fashion as Stable applications, as well as being used to trigger an automated git push-based deployment to Heroku or similiar IAAS. Flexibility for development staff is the goal, rather than high availability, high performance, or scaling.
This tag will likely be used only to push to Heroku or similiar IAAS, outside the purvue of the DevOps group. Expectations for application type's high availability, scaling ease, and monitoring/alerting should be very minimal.
For Stable applications, any production-bound code, infrastructure, or system configuration changes must go through a security review prior to green lighting a production deployment.
For Immature and Prototype applications, security reviews are not automatically triggered by a new deployment, but are certainly encouraged and appreciated. Periodic security reviews should be performed at minimum.
Stable applications and Immature applications being deployed to AWS autoscaling infrastructure have any keys or configuration files with potentialy sensitive information(database creds, S3/AWS creds, API keys) can be injected via private system_configuration github repos and secured S3 buckets.
- How do we do deployments?
- Should Heroku on prod be the gold standard we aim for? (Nope, gold standard for stable apps is a bonafide autoscaling infrastructure on AWS. Heroku-style is good for prototype/immature apps, or for staging/dev envs on Stable apps.
- How do we deal with Heroku going down, can we do back-up deployments on Labs infrastructure? (The best way to deal with cloud DR is to do it yourself, I don't think Heroku can be counted on for stable apps. Building multi-region, multi-AZ in apples-to-apples envs is borderline trivial in AWS proper, much harder likely with 3rd party IAAS)
- We should mention security reviews in here somewhere
Fork this document! Improve it!