Guidelines for writing code, developing web apps and contributing to open source projects at the City of Detroit.
We don't follow all of these guidelines perfectly ourselves yet, but are working towards them.
Our goal is to:
- build consistency across our development teams around the City
- make our repos more friendly through better documentation, meaning we want anyone to be able to get the gist of what the project is, get up and running quickly and contribute
Get in touch with our developers by email at firstname.lastname@example.org.
All of our project repositories assume that you:
- have basic knowledge of the Unix environment and are familiar with the command line
- have basic knowledge of Git and Github
- have no clue about what the project does or how to get started
As works of the government, all of our projects and code are in the public domain within the United States. Read the full details here: LICENSE.md
MIT license in your
package.json file, and then copy
LICENSE.md into your repo.
READMEs explain what the project is, how to install dependencies and how to get up and running for local development.
Get started with this outline: README_TEMPLATE.md
Projects & Wiki
Github Projects & Wikis are another nice place to keep notes about concepts, tools, roadmaps or change logs related to your repo without cluttering the README.
Branching helps manage a development workflow by keeping in-progress code separate from production code.
Avoid developing on and committing directly to the
master branch; assume
master always has working, deployable code.
During development, branch off
master to build out new features and fix bugs. When it makes sense, name branches by their issue number or feature description, eg
Master then accepts pull requests from branches.
Linters keep our code looking clean and working well.
Notes about test coverage coming soon.
We work in the open and welcome your feedback, both in the form of ideas and code. Learn about submitting issues and pull requests below, or send us an email if you have a question!
Contributions to a project might entail:
- bug reports
- new feature suggestions
- code patches
- improved documentation
- test coverage
Issues help track and manage feature requests, enhancements and bug fixes.
As long as you have a Github account (it's free to sign up if you don't yet), you can leave us an issue within a project. Issues look like this: ISSUE_TEMPLATE.md
When you fix an issue, include the issue number in the commit message to automatically close it and keep a reference link to the commit number, eg
git commit -m 'added map, closes #8'. Issues can also be referenced and closed in pull requests.
Pull requests are used to propose changes from your own branch or fork to the
master branch of the project. Your changes might be a single commit, or a series of many commits; sometimes it makes sense to squash many commits into a single one before submitting a pull request (more on that here).
Pull requests look like this: PULL_REQUEST_TEMPLATE.md
All pull request contributions will be released under the project's public domain license. By submitting a PR, you agree to comply with this waiver of copyright interest.
We review PRs and leave comments if something should be tweaked before it's merged. As tempting as it is to open and close your own PR to merge your changes over quickly, ask for an extra set of eyes first! Use the
assign feature to get someone else's attention.
Many of our projects are built on City of Detroit open data. These datasets are also made available through a public domain license. All datasets are accessible as static exports or by rest APIs as JSON and GeoJSON.
Find data at: