Permalink
Find file Copy path
106 lines (63 sloc) 7.85 KB

Contribution Guidelines

👊   How to contribute

  1. Thanks already!
  2. Pick an issue. We've labeled some of them with Good-first-issue to help you find the more accessible ones to start with.
  3. In the issue you chose to work on comment to let us know you’re working on it (to avoid two people doing the same thing). The comment should include a mention to @mattia-io (our project lead).
  4. Fork the project, or make a new feature branch from the master branch
  5. Do your magic, and make sure your git branch is up to date
  6. Make a pull request back to our master branch

Note: If you can’t find anything in our todo list that you can help with, it’s probably because we haven’t defined it yet. There’s lots of stuff to do, so if you think you can help out, let us know and we’ll find you something.

📟   Getting started

  • Fork the repository

  • Clone the projet from the fork you have created previously at first step : git clone https://github.com/your-github-user/onearmy.git

  • Install dependencies yarn

  • Run the dev server yarn start

Note: Builds are currently tested on Chrome/Firefox. If your browser is not supported, then consider contributing :-)

🏠   Project Structure

The project is split across pages which make up the visual routing of the application. Within pages there are components, some of which are specific to the page and others which are shared.

Typescript models that relate to general data flow (such as a user’s profile) are within the models folder, whilst component states and properties are declared within the component. Artificial data for use in development is held in the mocks folder, with live data requests handled within api.

In addition app state, actions and dispatchers are handled within the stores folder, whilst global state property mapping is dealt in page components.

🌳   Branch Structure

We have two main branches linked to production and development sites, you should always start with the master branch as this contains the most up-to-date code, and will be where pull requests are made to for review. The production branch contains the live production site, and will be merged from master after regular review periods.

We use additional branches to define a specific feature or issue group being worked on. An example might be work on the home page, which would be done in the ‘#19 home-page’ branch (where #19 refers to the issue number describing what needs to be done). These branches are ephemeral, and so removed after merging into the master branch and closing the issue. Generally it is expected that only 1 developer will be working on a given branch, and it is that developer’s responsibility to create the branch, manage pull requests, reviews or ask for additional support when needed.

🚀   Deployment

Master is our current development leading branch, and will autodeploy to the development site. When things are production ready, they will be pushed to the master branch which ends up on the live site.

💌   Epics and User stories

As the project will get quite complex we use Epics and User stories to break down functionalities into smaller action items that can be worked on from our distributed team of contributors (remote and inhouse). More in details:

  • Epics are pages and complex pieces of functionality.
  • User Stories break down epics into tiny, actionable items that are easier to take on for devs both remote or on site.

If you’re interested, here you can find a backlog document outlining the full list of upcoming Epics and relevant User Stories waiting to be developed. Project lead @mattia-io will transfer User Stories from here to Waffle where they're called Issues.

Anyone can pick an Issue from Waffle and get on with coding. When working on an Issue you should comment on the issue with your name, delivery date, plus a mention to Mattia (@mattia-io). This way we can be aware of what is being worked on and when issues are due for delivery. If upon assigning yourself an Issues you find that you are unable to contribute to it we kindly ask you to let @mattia-io know on the same Issues (max 2 weeks).

🐛   Issue Tracking and Management

Issues are tracked on GitHub and we also use waffle as a visual overlay to monitor progression. Some issues are collated to form Epics which are a more general narrative or story for what the intended development will result in for a user, and Issues may also have further child issues. If you are unfamiliar with ways to format or format issues, then refer to the links here.

Anybody can create an issue or assign an issue to themselves (can't assign on Waffle, in this case you should comment your name), and when working on an issue it should be tagged with in-progress (on Waffle @mattia-io will take care of this) so that we are aware of what is being worked on. Once an issue is in progress we expect some sort of update to be made within a 1-2 week period (otherwise you should unmark, and possibly unassign if unlikely to come back to it soon).

When a group of issues has been resolved a pull request to the dev branch should be made, where it will undergo a quick review and test. It is expected that the developer will have done through testing themselves first, and most pull requests can be quickly merged.

🤓   Javascript style guide

As this is a large project spread across many developers it is important that not only code is clean but also consistent. We use the prettier style guide to enforce certain conventions through the linting system – if using VSCode it is recommended that you include the prettier plugin to track errors in real time.

We also expect code to follow standard good practice, such as sensible variable naming, informative comments and avoiding files large than a couple hundred lines of code (emphasis on usability and reusability).

💅   Visual style guide

(More details coming soon)

For now you should use materialUI components where possible, as these will form a basis for future design principles.

🤝   Joining the team

We are always open to have more people involved. If you would like to contribute more often, we would love to welcome you to the team. Just send a quick email, introducing yourself and outline:

  1. Your experience working with the technologies listed above
  2. How much time you feel you can dedicate to the project

We ask this so that we can better understand how you might fit in with the rest of the team, and maximise your contributions. From here we will then connect you to the github repository as well as slack channel which we use to handle regular communication.

📚   Ressources