Skip to content

Latest commit

 

History

History
95 lines (63 loc) · 4.03 KB

CONTRIBUTING.md

File metadata and controls

95 lines (63 loc) · 4.03 KB
Raw

Contributing

Thank you for your interest in contributing to BuzzFeed's SSO!

Code of Conduct

Help us keep SSO open and inclusive. Please read and follow our Code of Conduct.

Getting Started

The Basics

If you've never contributed to a project on Github before, take a look at Rob Allen's beginner's guide to contributing to a Github project.

  • Make sure you have a GitHub account
  • Submit a ticket for your issue, assuming one does not already exist. In that issue:
    • Clearly describe the issue including steps to reproduce when it is a bug
    • Identify specific versions of the binaries and client libraries
  • Fork the repository on GitHub

Making Changes

  • Create a branch from where you want to base your work
    • We typically name branches according to the following format: helpful_name_<issue_number>
  • Make commits of logical units
  • Make sure your commit messages are in a clear and readable format, example:
sso: added structured logging

* use Logrus to add structured logging
* update logging documentation
* ...

Quickstart

If you want to get SSO up and running, please see our quickstart guide.

Running Tests

All bug fixes and new features are expected to include tests, so it's helpful to know how to run them locally while you're developing!

Here are the steps to running the tests for SSO:

  1. Install go

  2. Be sure to set your workspace directory and set your GOPATH

  3. Add the sso repo to your gopath:

    ln -s path/to/sso $GOPATH/src/github.com/buzzfeed/sso

  4. Install gpm and dependencies:

    brew install gpm
gpm install

  5. Run the tests in the root directory

    ./scripts/test

Submitting Changes

  • Push your changes to your branch in your fork of the repository
  • Submit a pull request against BuzzFeed's repository
  • Comment in the pull request when you're ready for the changes to be reviewed: "ready for review"

Code Review

Changes to buzzfeed/sso happen via GitHub pull requests, which is where at least one other engineer reviews and approves all code changes. Some tips for pull requests and code review:

  • Each pull request is a branch from main — there are no other long-lived branches
  • A single pull request is used for each set of changes — i.e., once a pull request has been opened, any follow-up commits to address code review and discussion should be pushed to that pull request instead of a new one
  • Before a pull request is merged, it must get a green check mark from our CI for passing tests
  • Before a pull request is merged, the author should take the opportunity to clean up and rewrite the commits on the branch (see How to Write a Git Commit Message.
  • A maintainer will merge your changes once they're approved and ready!
  • Most importantly: Practice mindful communication!

Merge Policy

In order to allow SSO to be the most useful, while balancing feature needs with security concerns, we take an Optimistic Merge approach, which means:

  • We will do our best to merge every contribution that enables a requested feature or solves an issue that blocks folks using SSO.
  • As we find more efficient, secure, or otherwise stronger solutions, we will deprecate old features and replace them.

Our strategy will be to announce deprecation as part of a stable release, and remove functionality as part of the next stable release. While this is a very quick cycle, we believe it is the best approach for keeping SSO up to date and preventing reliance on outdated featuresets.