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.
- Code of conduct
- Getting started
- Issue Tracking and Management
- Project structure
- Branch structure
- Why haven't you used ...
- Joining the team
👐 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 behavior to firstname.lastname@example.org.
The platform is built in React and Typescript for typing and consistency, styled-components 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.
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
Fork the repository
Clone the project from the fork you have created previously at first step :
git clone https://github.com/your-github-user
Run the dev server
Run the end-to-end tests
Run the component documentation
Open the Cypress Test Runner
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: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 it easily 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 labeled 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.
🏠 Project Structure
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, and will be synced with 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 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.
Master is our current development leading branch, and will autodeploy to the development site with Travis CI.
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).
😖 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 just 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:
- Start with an observation - instead of asking 'do you use redux' take a look at the
package.jsonand see for yourself.
- 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.
- Clearly state what you believe the benefits to the project would be - simply '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.
- 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. Just send a quick email, introducing yourself and outline:
- Your experience working with the technologies listed above
- 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.
- https://www.udemy.com/react-redux/ paid online course to cover most of the basics of React - it uses redux where we use mobx but the rest is still very good
https://levelup.gitconnected.com/typescript-and-react-using-create-react-app-a-step-by-step-guide-to-setting-up-your-first-app-6deda70843a4 short intro app for typescript and react
https://medium.com/teachable/getting-started-with-react-typescript-mobx-and-webpack-4-8c680517c030 react-mobx-typescript example
https://medium.com/get-it-working/get-googles-firestore-working-with-react-c78f198d2364 react-firestore example
https://www.robinwieruch.de/complete-firebase-authentication-react-tutorial/ Example using Firebase auth with React and linking Redux state
https://testautomationu.applitools.com/cypress-tutorial/ Complete tutorial about the test automation tool Cypress