Welcome, and thank you for contributing to this project. Please take your time to study this document carefully before making any changes to the codebase, to ensure you're on the same page with the rest of the team and we can all collaborate seamlessly.
This project uses the Fork & Pull Model for receiving contributions. Read about the Fork & Pull Model here.
The main / original / upstream (hereinafter upstream) repository will have only two (2) branches - master and Develop. Additional hotfix branches may be created to work on critical bugs in the deployment.
'Develop' - The Integration branch. This is where features from the different forks are brought together. Group leads, submit your pull requests here. This is the default branch. An integration team will be responsible for bringing it all together and resolving any possible merge conflicts that may arise.
'master' - The deployment branch. The code on this branch goes live to our hosting servers and must be kept in pristine condition. When the integration (Develop) branch reaches a milestone, the deployment (master) branch is updated via pull request.
Hotfix branches. In the event that a bug slips past the integration team and makes it into deployment, a hotfix branch is created off of master. Prefix hotfix branch names with "hf__". On completion, this branch is merged with master, and also with Develop so the fixes are reflected in all future deployments.
Each fork represents work on a specific feature or task. Fork this repository to your own account and do all your work there. Do your work on the Develop branch or create a new branch for yourself, then create a pull request to the Develop branch of the main (upstream) repo. You may choose to rename your forked repo to include a description of what feature you are working on. Example: node-url-shortener__feature-name.
When working with many people on the same codebase, sometimes others make changes that affect your work. While great care has been taken to create a modular team workflow to keep this to a minimum, merge conflicts are inevitable. It would suck to finish working on a task or feature, only to find that the codebase has evolved and you need to rework everything to conform to the new changes. This is managed in two ways.
First, make sure your work is in line with our specifications. Understand the folder structure and stick to it. Study the tasks list on Pivotal Tracker and identify any tasks that your work may depend on or that relates to yours in some way. Contact the team leads or project managers if you need any clarification. Do your due dilligence to make sure you are on the same page with everyone else. This is your responsibility. Your submission may be rejected if it's non-compliant.
Second, each team member needs to make sure that at every given time, their working directory is up-to-date with the latest changes from the upstream Develop branch. This is achieved with a two-fold process.
After setting up your fork on github and cloning it locally on your system, you'll need to run a command just once to create a connection between your local repository and the remote upstream repository. Note that there's automatically a remote 'origin' repository set up when you clone. This points to your fork. Now you need to set up 'upstream' which will point to the central upstream repo.
- Open a terminal and go into the directory for the newly cloned repo. Now add the upstream remote like so:
git remote add upstream git://github.com/TEAM-NAME/REPO-NAME.git
PS: You may get an error saying the upstream remote has already been configured. If so, then you are good to go.
Now you're all set up.
The following steps must be run periodically to keep your work up-to-date! You can run these commands as often as every hour. You want to fetch any new changes as soon as possible. Each time you want to begin working, or take a break from your work, run these first.
Be sure to stash
or commit all local changes first.
- Switch to the Develop branch
git checkout Develop
- Get all remote upstream changes into your local computer.
git fetch upstream
- Merge changes fetched with your local Develop branch. ('Develop' must be the currently checked-out branch)
git merge upstream/Develop
- Push the newly merged changes to your fork's remote (online) repo. This is configured as 'origin' by default.
git push origin Develop
If you've created a new branch to work on rather than working directly on Develop, then run the next steps.
-
Switch to your feature branch.
git checkout your-feature-branch
-
Merge the changes on the newly merged Develop branch, into your feature branch.
git merge Develop
You may encounter merge conflicts here. Resolve them, then come back and complete the merge. If you merge often enough, any conflicts would be trivial and very few.
-
Finally, push your newly merged feature branch to the remote github server for backup.
git push origin your-feature-branch
src
├── config
├── constants.js
├── controllers
├── database
├── helpers
├── middlewares
├── models
├── routes
├── services
├── tests
└── views