Skip to content

Latest commit

 

History

History
94 lines (67 loc) · 6.2 KB

CONTRIBUTING.md

File metadata and controls

94 lines (67 loc) · 6.2 KB

Contribution guidelines

Ongoing development on this project is managed by this project board: https://github.com/neontribe/www/projects/6.

Getting tickets/issues ready to be worked on

Before a thing can be worked on it must be both created as an issue, and prioritised using a definition of done.

Creating issues

  1. Open the Issues tab and click New issue and choose the right template.
    • anyone can create issues
    • Bug is for bugs
    • Story is for new things, e.g. code, content to meet a user need
    • Tasks is for simple actions such as dependency updates, they are often repeatable and related to maintenance
    • Research is for tasks that are not going to effect the site yet
    • Catch-up Meeting is for the weekly catchup meeting Prioritising issues
  2. Follow the template so that the issue can be understood by others
    • the template explains what you need to fill out
    • don't worry about having everything, fill in as much as you can and focus on the Definition of done
  3. There is no need to attach the card to the project board, that step only happens during a prioritising session.

Prioritising issues

This takes place during a weekly catchup meeting when we need more issues for the project board, or when someone asks for a particular issue to be considered.

  1. View new issues using this filter: https://github.com/neontribe/www/issues.

  2. Decide whether the Definition of done is ready for action on a given ticket.

    • if further work is needed then assign a related action in the meeting notes

  3. Take tickets that are ready for action and add to Top priority issues or Backlog columns based on group instincts of user value.

    • not all tickets will be high enough priority to make it
    • decisions from previous meetings should not be revisited in the weekly cycle
    • if an issue is agreed to be 'high priority' but the approach to take is not yet decided add a 'requires discussion' label to the issue, AND add an action to the meeting to note that it will be discussed the following week, tagging people that may be particularly interested

  4. Document reason for decision on tickets, so that it makes sense later.

From time-to-time we may decide to hold more in depth prioritisation meetings to involve more people and to look at bigger issues.

Definition of done

These differ for each type of issue:

  • Bug Clear Expected Behaviour is what we use for the definition of done. It also needs clearly documented steps to reproduce the error so we can check the error has been elminated.
  • Story the definition of done uses Acceptance Criteria, this can be quite broad, specifically when the ticket is first created. We expect that the Acceptance Criteria will be refined during both prioritisation, and development, so that the final goal is clear and testable.
  • Task the description of the task usually contains its own definition of done, additional things such as security notes may be relevant.
  • Research will depend on the context and may be a simple statement of research aims.

Getting started on development

Any issues in the Top priority issues column are important enough and have been prioritised.

When contributing to this project please do the following:

  1. Pick something near the top of the Top priority issues column, which you feel you have the time and confidence to tackle.
    • We expect you to learn while tackling issues, please don't be put off by a tasks' seeming complexity.
  2. Check the Definition of done for the ticket to see if you understand it.
    • If you need more information please follow up with the person who spawned/created the task.
  3. Assign yourself and move the ticket to the In progress column.
  4. Create a branch with a name to help match it to the ticket, e.g.: 307-contrib-docs.
  5. Work on the feature branch, make small commits which include the reason for each commit's change.
    • We don't expect you to battle the problem alone, put any queries on the github issue and slack, people will help when they have time.
  6. When you're happy with the changeset/the commits you've made, and you're happy that the ticket passes its Definition of done create a pull request.
  7. now.sh will generate a build and deploy to a temporary URL which is available on your pull request page, along with the status of build.
    • ⭐ Check it ⭐
    • Both you and reviewers should check that the changes you've made are available on the temporary URL.
  8. Await code review, see Review process
    • Pull requests are the pull requester's responsibility, use slack and other channels to encourage people to review for you.
    • Before you merge, it is your responsibility to respond to suggestions and change requests.
    • It's not personal. Lots of comments can be a good thing, even if they're all suggesting changes.

Please make sure that you keep your activity up-to-date:

  1. take each ticket as far as you can, before taking another one (e.g. ready for code review)
    • if the ticket needs to be put on hold because you've reached the limit of your availability or understanding then;
      • put your findings/thoughts on the ticket
      • put the branch name (if any) on the ticket
      • unassign yourself and put it back in Top priority issues

Review process

Two or more tribers need to approve the pull request, often getting the person who wrote the ticket involved is best.

Review is about: checking for errors, checking that the work achieves the definition of done for the ticket, and also about suggestions for different solutions.

Always assume that the author is not trying to be an arsehole, isn't an idiot, and is probably operating under constraints that you don't understand. Be gentle and ask questions.

WIP:

Testing

is done using feature branch deploys on pull request