Developer Workflow

Thanks for contributing to the DataLab project.

Recommended Git Flow

All DataLab contributions are made via GitHub pull requests. Contributors are expected to adopt the rebase-and-squash based GitHub Flow, so that the repository maintains a clean history, while allowing you to work in parallel and make use of the GitHub features for code review.

Git Basics

If you need an intro or refresher on git, some content to check out:

• Simple Getting Started Guide
• Git Crash Course
• Git Basics
• Git Reference

Repository principles

• Master is assumed to always be stable and deployable. Work should be completed in branches or forks.
• Pull requests should always be submitted against the master branch.
• A pull requests represents a completed work item, or bug fix, but can be submitted anytime to trigger review or discussion of the work as it progresses.
• Pull requests are merged once they've been reviewed, and feedback has been addressed.

Developer configuration

Make sure you've setup your git configuration appropriately to identify yourself as the author of your commits.

git config --global user.name "Your Name"
git config --global user.email your@email.address

Typical feature development

The assumption here is you have locally cloned the repository. The following are the steps and associated git commands to follow when working on your feature:

# Get to a clean initial state and then create your feature branch
cd <your local repository>
git checkout master
git pull --rebase --prune
git checkout -b <branch name>

# Work on your changes and commit locally
git add .
git commit -m "Short descriptive text"
...

# Keep pushing your changes to origin, so they're generally visible
git push -u origin <branch name>

# Stay in sync with master, and push to your branch/fork
# often as you progress.
# First get all of your changes down to a single commit (if
# it makes sense to treat all individual commits as atomic)
git rebase -i origin/master
git checkout master
git pull --rebase
git checkout <branch name>
git rebase master
git pull --rebase
git push -u origin <branch name>
...

# Once ready for review, submit a pull request via GitHub.
# Make sure you've followed style guidelines, added and run
# tests as appropriate.
# Address feedback and review comments by committing
# locally and pushing (to update the pull request)

# Cleanup your local history to prepare for merging
git rebase -i origin/master
git push --force origin <branch_name>

Branches

Here is the simple naming convention when creating branches:

• feature/<feature_name> - for feature sized work
• issues/issue_# - for addressing specific issues