Guidelines for writing and contributing code
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
ISSUE_TEMPLATE.md
LICENSE.md
PULL_REQUEST_TEMPLATE.md
README.md
README_TEMPLATE.md

README.md

Code Standards

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 opendata@detroitmi.gov.

Assumptions

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 the project's language (Javascript, Python)
  • have basic knowledge of Git and Github
  • have no clue about what the project does or how to get started

Documentation starters

License

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

Use the MIT license in your package.json file, and then copy LICENSE.md into your repo.

README

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.

Code quality

Branches

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 HEAD of master to build out new features and fix bugs. When it makes sense, name branches by their issue number or feature description, eg 8-add-map.

Master then accepts pull requests from branches.

Linters

Linters keep our code looking clean and working well.

Try ESLint for Javascript and Pylint for Python projects. Packages are available for most editors.

Tests

Notes about test coverage coming soon.

Contributing

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

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

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.

Data resources

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: