Skip to content

Developer Guide

Jump to bottom
Ali.Abdolali edited this page May 10, 2021 · 1 revision

Development Workflow

The main steps are:

  1. Create an issue associated to the new development.
  2. Fork the AGW GitHub repository.
  3. Clone the forked repository to your local system.
  4. Add a Git remote for the original repository.
  5. Create a feature branch, make changes, commit and push changes to your GitHub fork.
  6. Communicate with the source repository managers (Ali Abdolali and Usama Kadri) to indicate what is being developed.
  7. Open a pull request from the new branch to the original repo.
  8. Clean up after your pull request is merged.

1.Create an issue associated to the new development.

  • Include the issue in the commit message.

  • Include the list of test(s) with expected changes due to this development.

  • Include the detail of the new/modified test to check this development.

  • Update the issue with relevant details if needed.

2. Fork the AGW GitHub Repo

  • Create and account on github.com,
  • On github.comfind the AGW trusted repository:
  • Locate and click the fork icon on the upper right-hand corner of the AGW GitHub page.

This creates a full copy of the AGW repository under your user account.

3. Clone the Forked Repo Locally

You can now navigate to your GitHub dashboard and choose the newly-created fork. To start your development work, you need to first create a local copy on your machine of your fork. To do that, you must git clone your fork locally. First, find the right address for the fork on your GitHub fork page clicking the "Clone or Download" dropdown menu. Then, on your local box:

git clone https://github.com/<username>/AGW.git

If you are using ssh:

git clone ssh://[email protected]/<username>/AGW.git

4. Add Remotes and update you fork/branch with authoritative repo

Remotes are GitHub repositories that are linked to your local copy. A first remote origin is automatically created when you clone a repo. In this case, that links your local copy to the fork you created in your GitHub account. You can keep your local copy synced with your fork and vice-versa by simply using commands such as git pull to sync the local copy with the fork, or git push the way around. We will also want to keep the local copy and your fork synced with changes made in the repository your forked from.

That is possible by creating a remote link within your local copy that points to the upstream repo:

git remote add upstream https://github.com/aliabdolali/AGW.git

or

git remote add upstream https://github.com/<username>/AGW.git

Sync with the main repo

Syncing your local copy to the upstream remote is done within your local copy by using the commands:

  • Change to the active development branch
    git checkout develop

  • Copy over changes to upstream repo
    git fetch upstream

  • Merge changes to your local repo
    git merge upstream/develop

  • Push changes to your GitHub fork
    git push

Likewise, when the master changes, you will want to sync your fork accordingly.

Using git push to upstream repos will fail, and should not be attempted.

5. Creating a feature Branch for Development Work

Adding new or modifying existing features of AGW should be done in a feature branch. This involves the development cycle steps below.

Before you get started, please note some rules of engagement here:

  • Send the managers of the repo you forked from an email indicating what you are planning to develop,

    • Authoritative repository code managers: Ali Abdolali and Usama Kadri

  • Create one feature branch for every single feature or single bugfix you will be working on. Do not bundle all features or bugfixes in a single branch,

    • This creates a situation where undeveloped features will get in the way of reintegrating mature work,
    • Pull requests with more than one feature per branch will be returned.

The development cycle steps:

  • Create a new feature branch from the develop branch git checkout -b <branch name> develop
  • Make changes to the files,
  • Test your changes using the examples
  • Frequently commit your changes to the branch.
    • Check changes made
      git status
    • Add files indicated by status
      git add <some files>
    • Commit changes locally,
      • Use a commit message in the form "branchname>: [description of changes]":
        git commit -m "<branch name>: [description of changes and files affected]"
  • Push changes to your GitHub fork
    git push origin <branch name>:<branch name>

7. Reintegrate to Main Repo: Open a Pull Request

Pull requests are proposed changes to a repository submitted by a user and accepted or rejected by the main repo code managers. This should happen when you made changes in one of your feature branches that are mature and could become part of the AGW package. When you get to that point, follow the guidelines well-established in GitHub:

  • Using your browser, navigate to the original repository you created your fork from.

    • To the right of the Branch menu, click New pull request.

  • On the Compare page, click the highlighted link compare across forks.

  • Confirm that the base fork is the repository you'd like to merge changes into.

    • Use the base branch drop-down menu to select the branch of the upstream repository you'd like to merge changes into.

  • Use the head fork drop-down menu to select your fork,

    • then use the compare branch drop-down menu to select the branch you made your changes in.

  • Type a title and description for your pull request.

  • If you do not want to allow anyone with push access to the upstream repository to make changes to your PR, unselect Allow edits from maintainers.

  • To create a pull request that is ready for review, click Create Pull Request.

    • To create a draft pull request, use the drop-down and select Create Draft Pull Request, then click Draft Pull Request.

For more information about draft pull requests, see About pull requests"

8. Clean up after your pull request is merged.

Depending on if the code managers accept your new features/changes into the DEVELOP branch (note it will first go into a feature branch on the fork), you may either restart the development cycle, or have completed your work on that feature. If the work is complete and your changes are reintegrated into the develop branch (not just a branch on the fork), then its time to clean up!

  1. Update your local clone from the upstream develop branch (see Sync with upstream remote).

  2. The changes are already in the main repo's develop branch, its time to delete the feature branch locally,

git branch -d <branch name>

  1. Update the master branch in your forked repository,

git push origin master

  1. Push the deletion of the feature branch to your GitHub repo,

git push --delete origin <branch name>

Contact AGW Code Managers if you have any questions or suggestions that may improve our collaboration.

Testing in AGW

A series of example tests are prepared to check the AGW with different options and assumptions. Developers are encouraged to check their implementations with the tests them. example tests are enforced when new master or develop branches are created, and this typically involves running a complete set including all available example tests with different configurations (see “The Matrix” section below). If you add new features, it is also encouraged that you add a test for the new feature.

The following tests are available under example directory:

Test Label Description
shortest_path_dijkstra Find shortest travel time from Epicenter to hot points
transect_extractor_arc Find the shortest Arc and transect from Epicenter to hot points.
Clone this wiki locally