Skip to content

Latest commit

 

History

History
182 lines (118 loc) · 13.8 KB

CONTRIBUTING.md

File metadata and controls

182 lines (118 loc) · 13.8 KB
Raw

react

Contribution Guidelines

Thanks for being here already! You'll find all the information you need to start contributing to the project. Make sure to read them before submitting your contribution.

If you think something is missing, consider sending us a PR.

🍽  Summary

👐   Code of Conduct

This project and everyone participating in it is governed by the Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behaviour to [email protected].

🤖   Technologies

Frontend

The platform is built in React and Typescript for typing and consistency, Emotion for reusability and component based styling. We created a frontend guide to explain our choices and best practice in building the One Army interface. This guide is available in the wiki.

Backend

Our backend contains microservices in Node and is based on Firebase's Firestore to manage our database.

You can find useful links to learn more about these technologies in the resources section.

📟   Getting started

Prerequisites

With the above tools available, you are ready:

  1. Fork the repository.

  2. Clone the project from the fork you have created previously at first step : git clone https://github.com/your-github-user/community-platform.git

  3. Install dependencies yarn

  4. Run the dev server yarn start

  5. Run the end-to-end tests yarn test

Additional commands

  • Run the component documentation yarn storybook

We use Cypress to carry out end-to-end testing. For more information about how to setup, use and add tests refer to the sections in the Testing Setup Wiki.

We use BrowserStack to test our platform on multiple devices and browsers. Note: Builds are currently tested on Chrome/Firefox. If your browser is not supported, then consider contributing.

🐛   Issue Tracking and Management

Issues are tracked on GitHub. Use the labels to filter them to your needs and/or skills. Anybody can create an issue or feature request, but be sure to use our templates if you want your voice to be heard. Some issues are collated to form modules which are the parent of each section of the platform. Modules are then split into pages and finally components. You can navigate through them by filtering with the labels Type:Module and Type:Pages. Having a look at module and pages issues is the best way to get a clear overview of the ongoing work on it.

Additionally if you have identified a bug you may want to write a test to make reproducible (and less likely to arise in the future). You can find more information to do this in the Testing Bugs Wiki

We've also labelled some of the issues with Good-first-issue to help you get started quickly. When you start working on an issue, comment on it or if your are a registered contributor assign yourself to let us know so we avoid working on something twice. The comment should include a mention to @mattia-io (our project lead).

When a group of issues have been resolved a pull request to the master branch should be made, where it will undergo a quick review and test. It is expected that the developer will have done thorough testing themselves first, this helps make sure most pull requests get merged quickly.

🤑   Development Bounties

We have a small bounty system as a way of saying thanks to developers for contributing their time and code. Find out more about it in Bounties

🏠   Project Structure

  • scripts & config : contains build-related scripts and configuration files. Usually, you don't need to touch them.

  • cypress : contains the test automation of End-to-end tests.

  • functions : contains the backend firebase related functions.

  • src : contains the source code. The codebase is written in ES2015.

    • assets : contains assets such as icons/images.
    • components : general stateless components that compose the app.
    • mocks : artificial data for use in development.
    • models : here you will find the general data flow, such as a user's profile, while component states and properties are declared within the component.
    • pages : makes up the visual routing of the application. Each folder then corresponds to a section or module of the platform.
      • common : contains stateful components that are shared between all pages.
    • stores : In addition to app state, the store folder contains actions and dispatchers, while global state property mapping is dealt with in page components.
    • theme : contains theme files that define the general interface style values.
    • utils : contains global utility functions, e.g. firebase database helper.

  • types : contains TypeScript type definitions

🌳   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 added for review. The production branch contains the live production site, PRs are automatically raised that will merge changes in from master. Maintainers are responsible for merging these PRs.

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 will be removed after merging into master, followed by 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 the pull request, reviews and ask for additional support when needed.

🚀   Deployment

The master branch is our current development leading branch, and will auto-deploy to the development site. The production branch deploys to the live community platform site

🤓   Javascript style guide

As this is a large project spread across many developers it is important that the code is both clean and consistent. We use the Prettier style guide to enforce certain conventions through the linting system – if using VSCode (which we highly recommend) it is recommended that you install and setup the prettier plugin to track errors in real time.

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

Running yarn format from the project route prior to committing will ensure the code you're adding is formatted to align with the standards of this project.

🔬   Commit style guide

To help everyone with understanding the commit history of this project and support our automated release tooling the following commit rules are enforced.

  • commit message format of $type($scope): $message, for example: docs: add commit style guide
  • maximum of 100 characters

For those of you who work with git hooks, this project offers a husky commit message as well.

Here's a more detailed explanation of how you can format the commit message heading:

<type>(<scope>): <short summary>
  │       │             │
  │       │             └─⫸ Summary in present tense. Not capitalized. No period at the end.
  │       │
  │       └─⫸ Commit Scope (optional): platform|docs|storybook|functions|scripts
  │
  └─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test

😖 Why haven't you used [insert favourite language/framework/convention here]

As an open-source project most of our decisions up till now have been guided by the people writing the code and conversations with people in our community whose opinions we value and respect. Some things are by careful design after the result of lengthy discussions, others are individual preference with few complaints to date. As we both want to encourage input from newer contributors but also want to avoid getting bogged down in circular or repetitive debates we encourage you to:

  1. Start with an observation - instead of asking 'do you use redux' take a look at the package.json and see for yourself.
  2. See if this is something we've already talked about - we tracked some initial discussions here PPv4 - Web Platform Discussions, and are trying to add more of the ongoing discussions to the GitHub Wiki. There is also plenty more within Slack #v4-website-dev channel, which we hope to slowly migrate onto the wiki.
  3. State what you believe the benefits to the project would be - 'because I've used it before and like it' isn't good enough! Do your research, evaluate common alternatives (in the very least google '[my awesome thought] vs X' and read the first few articles. Try to present a balanced argument for why we might want to/not want to use something.
  4. Be willing to support implementation - any great idea or suggestion will have direct impact on others contributing to the project. If there is something you feel strongly about you should first create a clean, clear demo of how it would work in practice, and be willing to provide additional guidance if called upon.

🤝   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. Send us 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.

📚   Resources