Development Process for AMS

Because some people are not as familiar with how to use Git/Github to develop using a team approach, this page will describe the process.

Clone the projects from GitHub

The first step is to clone both repositories from GitHub. The repository URLs are:

ams-client: https://github.com/gpdoud/ams-client.git
ams-server: https://github.com/gpdoud/ams-server.git

1. Create a folder on your workstation called ams.
2. cd into the ams folder
3. type git clone https://github.com/gpdoud/ams-client.git
4. type git clone https://github.com/gpdoud/ams-server.git
5. cd into ams-client
6. type npm install

Now you have the source code ready to run. It is very important that you run the application right after cloning it. Otherwise, you may not be able to determine wether it doesn't run because of your change or there was something wrong with the cloning.

Making a change

1. Create a development branch

It is important that you create a development branch from the current branch before beginning to make changes. No one can push changes directly back to the main branch. Assuming the current branch is called dev1, you create your branch with a name like this:

[your 2 char initials]-[issue number]-[descriptive text]

So if I was going to create a branch to address issue number 7 to create a help page, the branch name would be gd-7-help-page.

git checkout -b [branchname]

This creates the new branch and changes into that branch. Now you can begin making code changes.

2. Document your changes

Because it is likely someone else will be making changes to this code, you should use reasonable comments in your code to describe what the purpose of the code and why the code is needed. For most comments, a few words are fine. If there is some code that is particularly complex, a few lines usually does the trick. Use good judgement as to how much is needed. Sometimes it is good to ask a colleague their opinion.

3. Test your work well

Do not rush. We would rather take longer and deliver good quality work than to rush it and end up with bugs we have to fix in a hurry. Do double check for warnings in the build process and try to clean all of them up.

As we progress through this project, we'll likely being including automated testing in the process.

Do not merge your changed back into the dev1 branch at this time.

4. Push your changes to a branch in GitHub

When you're ready, you push your committed work up to GitHub to a branch with the same name as your development branch. It is easy to do:

git push origin [branchname]

This stores your code in a branch on GitHub safe and sound.

5. Enter a Pull Request

This is usually the step many have not done before especially if you've never worked on a team project using GitHub.

A pull request is created on GitHub and it is a request to merge a branch into another branch. When you create it, you specify your development branch be merged back into where your originally branched from. So if you branched from dev1, you would merge your branch back into dev1. The Pull Request includes notes from you about your changes and should include any special instructions.

The pull request will be reviewed by one other person on the team. When everything is good, it will be merged into the dev1 branch. If there is something wrong or there are questions about your work, it will be entered into the pull request your created. You can answer the question and, if needed, make any associated changes to your code.

6. Pull changes from dev1 to your local repo

Once your changes are in dev1, you should pull those down to your local dev1 branch.

git pull origin dev1

This brings down all your changes and any other changes to dev1 that you may not have.

7. Remove your local development branch

The changes in your development branch are no longer needed since they are in the dev1 branch. Remove the branch.

git branch -d [branchname]

Assuming there are no uncommited changes, this deletes your branch. If there are uncommited changes that you know are not important, you can force the branch to be deleted anyway with this command.

git branch -D [branchname]