Skip to content

Latest commit

 

History

History
109 lines (75 loc) · 5.72 KB

CONTRIBUTING.md

File metadata and controls

109 lines (75 loc) · 5.72 KB
Raw

Welcome!

We’re so glad you’re thinking about contributing to a Technology Transformation Services (TTS) open source project! If you’re unsure about anything, just ask — or submit your issue or pull request anyway. The worst that can happen is we’ll politely ask you to change something. We appreciate all friendly contributions.

TTS is committed to building a safe, welcoming, harassment-free culture for everyone. We expect everyone on the TTS team and everyone within TTS spaces, including contributors to our projects, to follow the TTS Code of Conduct.

We encourage you to read this project’s CONTRIBUTING policy (you are here), its LICENSE, and its README. When you are ready to make a pull request, read our pull request process, which is a part of the Login.gov Handbook.

If you have any questions or want to read more, check out the 18F Open Source Policy GitHub repository, or send us an email.

Pull request guidelines

Below are rules we strive to follow to achieve maintainable and consistent code.

Commit message style guide:

  • Write your commit message summary in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert.

  • Under the summary, start by explaining why this change is necessary, and add details to help the person reviewing your code understand what your pull request is about.

  • If the pull request is in response to a Jira ticket, include the ticket ID in the commit title (e.g. "LG-1234 Add the stuff to the thing")

  • Include a changelog message which describes the changes in human-readable terms. Refer to the Changelog Messages section below for specific changelog requirements.

Example:

LG-1235 Load seed using before(:suite) in RSpec config

**Why**:
- Loading the seed in a `before(:each)` block results in an unnecessary
database call before every single test, slowing down the test suite,
and making development less efficient.

**How**:
- Use `before(:suite)` instead, since the data that is loaded is not
meant to change, and so that only one database call is made.
- To prevent the data from being wiped out after each spec, configure
Database Cleaner to ignore those static tables.

changelog: Internal, Automated Testing, Improve performance of test suite

Changelog Messages

You must include a changelog message in one commit of your pull request. The changelog message describes the changes in human-readable terms. These messages are included in release notes, so they should be easy to understand for our partners and users.

A changelog message should be written in the following format:

changelog: [Category], [Subcategory], [Description]

Replace [Category], [Subcategory], and [Description] with text relevant for your changes:

  • Category must be one of the following:
    • User-Facing Improvements are improvements to the application experience benefitting the end-user, such as a new UI component or updated text.
    • Bug Fixes are corrections to a broken behavior, such as preventing a raised exception.
    • Internal are changes which benefit the Login.gov team, such as analytics or code quality.
    • Upcoming Features are iterations contributing to a feature which has not yet been enabled for users in production.
  • Subcategory can be any value, but it cannot contain commas. Try to maintain consistency with changesets affecting similar parts of the application (for example, "In-person proofing").
  • Description is a plain language description of the specific changes.

If multiple pull requests iterate on the same feature, it's a good idea to use the same commit message, since identical messages will be combined into a single entry when the release notes are compiled.

In the rare case that a change should not be included in release notes, add [skip changelog] to the commit.

Additional notes on pull requests and code reviews

Please follow our Code Review guidelines. Glen Sanford's thoughts on code reviews are also well worth reading.

  • Keep pull requests as small as possible, and focused on a single topic
  • Once a pull request is good to go, the person who opened it squashes related commits together, merges it, then deletes the branch.

Everyone is encouraged to participate in code review. To solicit feedback from specific people, consider adding individuals or groups as requested reviewers on your pull request. Most internal product teams have a team handle which can be used to notify everyone on that team.

Public domain

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.