Skip to content

Latest commit

 

History

History
128 lines (75 loc) · 7.64 KB

CONTRIBUTING.md

File metadata and controls

128 lines (75 loc) · 7.64 KB

Contributing to WebSiteOneBackendApi (WSO)

So you'd like to contribute to the WebSiteOneBackendApi codebase? That's wonderful, we're excited to have your help :-)

Please do come and say hello in our Slack chat. You can get an invite by signing up at AgileVentures or emailing [email protected]. We have weekly meetings to coordinate our efforts and we try to do planning poker voting on tickets before starting work on them. Feel free to join any AgileVentures daily scrum to ask questions, to listen in, or just say hi :-)

Getting Started

This describes how to contribute to WebSiteOneBackendApi: the tools we use to track and coordinate the work that is happening and that needs to happen. This also describes the workflow -- the processes and sequences for getting contributions merged into the project in an organized and coherent way.

First be sure that you've set up your development environment following all the steps in Setting Up for Development on WebSiteOneBackendApi (Project Set Up)

We keep our code on GitHub and use git for version control.

General Steps

To get involved please follow these steps:

1. Get the system working on your development environment:

  1. install WSO on your dev environment (laptop or c9)

  2. get tests passing (unit tests in spec/)

  3. check that the site can be run manually (locally)

  4. (optional) deploy to a remote (e.g. Heroku, drie etc.) and ensure it runs there

2. Look at what needs to be done on GitHub

  • review open PRs on GitHub - leave comments or collaborate if interested

3. Look at what needs to be done on our zenhub project board:

  1. look through New issues column - feel free to start work, but always interested to hear chat in slack, scrum wherever

  2. look at backlog - if there is an interesting ticket get it voted on in a scrum or do an ASYNC Vote in Slack

Voting

Items need to be voted on before work can start. Voting happens in scrums or the weekly meeting. Note that even without the meetings you can get a vote on any issue you're thinking of working on by using the Async voting bot in the #websiteone slack channel, using the following syntax: /voter ISSUE NAME https://github.com/AgileVentures/WebsiteOneBackendApi/issues/number.

e.g.

/voter make a press-kit link in the footer https://github.com/AgileVentures/WebsiteOneBackendApi/issues/1738

More on how to handle a vote can be found at: https://github.com/AgileVentures/AgileVentures/blob/master/ASYNC_VOTING.md#automated-async-vote

git and GitHub

Our default working branch is develop. We do work by creating branches off develop for new features and bugfixes.

Any feature should include appropriate RSpec unit tests.

A bugfix may include a unit test depending on where the bug occurred, but fixing a bug should start with the creation of a test that replicates the bug, so that any bugfix submission will include an appropriate test as well as the fix itself.

Each developer will usually work with a fork of the main repository on Agile Ventures. Before starting work on a new feature or bugfix, please ensure you have synced your fork to upstream/develop:

git pull upstream develop

Note that you should be re-syncing daily (even hourly at very active times) on your feature/bugfix branch to ensure that you are always building on top of very latest develop code.

Pull Requests: naming, syncing, size

Here is how to create and submit a pull requests.

Every pull request should refer to a corresponding GitHub issue, and when you create feature/bug-fix branches please include the id of the relevant issue, e.g.

git checkout -b 799_add_contributing_md

Please ensure that each commit in your pull request makes a single coherent change and that the overall pull request only includes commits related to the specific GitHub issue that the pull request is addressing. This helps the project managers understand the PRs and merge them more quickly.

Whatever you are working on, or however far you get please do open a "Work in Progress" (WIP) pull request (just prepend your PR title with "[WIP]" ) so that others in the team can comment on your approach. Even if you hate your horrible code :-) please throw it up there and we'll help guide your code to fit in with the rest of the project.

Before you make a pull request it is a great idea to sync again to the upstream develop branch to reduce the chance that there will be any merge conflicts arising from other PRs that have been merged to develop since you started work:

git pull upstream develop

In your pull request description please include a sensible description of your code and a tag fixes #<issue-id> e.g. :

This PR adds a CONTRIBUTING.md file and a docs directory

fixes #799

which will associate the pull request with the issue in the Waffle board.

This all adds up to a work flow that should look something like this:

  1. ensure issue has full description of change and has been voted on
  2. create branch prefixed with id of issue (moves issue into 'in progress')
  3. create failing test on the branch (acceptance level)
  4. create failing tests (unit level)
  5. get test to pass with functionality
  6. submit pull request with fixes #xyz
  7. pull request reviewed
  8. changes to original PR if required
  9. pull request merged (presence of "fixes #xyz" then moves issue to 'done')
  10. code moved to staging and checked against production data clone
  11. code moved to production

Pull Request Review

Currently https://github.com/tansaku is project managing WebSiteOneBackendApi. The project manager will review your pull request as soon as possible. Usually the project manager will need to sign off in order to merge a pull request.

The project manager will review the pull request for coherence with the specified feature or bug fix, and give feedback on code quality, user experience, documentation and git style. Please respond to comments from the project managers with explanation, or further commits to your pull request in order to get merged in as quickly as possible.

To maximize flexibility add the project manager as a collaborator to your WebSiteOneBackendApi fork in order to allow them to help you fix your pull request, but this is not required.

If your tests are passing locally, but failing on CI, please have a look at the fails and if you can't fix, please do reach out to the project manager.