Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
139 lines (104 loc) · 5.04 KB

CONTRIBUTING.md

File metadata and controls

139 lines (104 loc) · 5.04 KB

Contributing

Overview

SCALE happens once a year but the team has ongoing projects and prep year round. If you are interesting in volunteering please request to join our mailing list: https://lists.linuxfests.org/cgi-bin/mailman/listinfo/tech

Git

This repository leverages a workflow for committing code called Github Flow. Below briefly explains how to create a feature branch and put in a pull request to add fixes and features to the code base.

This workflow was chosen for its simplicity and the fact that anything merged to master should be deployable. Github Flow allows developers have the freedom to work on changes in feature branches without effecting what's deployable, other team members work, or removing commit history. For more documentation on Github Flow see: https://guides.github.com/introduction/flow/

The Flow

  1. Clone down this repo:

    git clone git@github.com:socallinuxexpo/scale-network.git

  2. Create a feature branch from the repository. Make this branch name related to the work being done. The following example makes a feature branch for adding coolscript.sh to the repo:

    cd scale-network
git checkout -b adding_coolscript

  3. On this new branch go ahead and create, edit, rename, move, or delete files. For example lets create, add and commit coolscript.sh to the repo:

    cat << EOF > coolscript.sh
#!/bin/sh
echo "This script is so cool"
EOF
git add coolscript.sh
git commit -m "Adding coolscript"

  4. Push up this new branch up to Github:

    git push origin adding_coolscript

    Note: This assumes write access to branches other than master in the scale-network branch. Reach out to a team member via the mailing list for access.

  5. Create a pull request the feature branch against master with the proposed changes to kick off a discussion. Make sure to fill out the PR template with as much information as possible regarding the changes. The pull request can be titled with either the [WAIT] or [READY] flag. PRs with [WAIT] signify that the author does not yet wish for the PR to be approved as further modifications and conversation are expected. Any PR with the title omitting either [WAIT] or [READY] should be assumed to be [READY].

  6. If further changes are needed before the pull request is merged repeat steps #2 and #3. Your existing pull request will update automatically!

  7. Any PR in [WAIT] will be held at this state until the author is ready for a merge. Once ready the title should be editted to reflect [READY].

  8. Once in [READY] another SCALE Tech member will review the PR. The reviewer should ensure that the changes being proposed conform to the spirit of the existing efforts and do their best to test any changes manually to ensure accuracy. The reviewer should also verify that all CI checks are passing at this time. No PR with failing test should ever be approved under normal circumstances.

  9. The approving reviewer should then merge the PR, ensuring all CI checks are passing against master.

  10. Once your branch is merged, sit back and pat yourself on the back for improving the repo! Now go back to the master branch which is the default branch and get the changes that were merged with your feature branch:

    git checkout master
git pull --rebase origin master
git log  # Check to make sure the merge exists

  11. Go back to step #1 and add more fix and/or features to the repo!

Common Scenarios

  • Q: When working on a feature branch for a while and it needs to get the latest changes that have been merged against master. How is that done?

    A: That's easy! First make sure the feature branch has everything your working on committed. Then go back to the master branch, pull --rebase to get the latest changes from the Github master branch, go back to the feature branch and rebase master against it. So it looks something like this:

    git checkout master
git pull --rebase origin master
git checkout <feature_branch>
git rebase master

    Any subsequent push to the remote will require a force push since history was rewritten instead of just appended to:

    git push -f origin <feature_branch>

  • Q: How can I checkout an existing remote branch on another machine?

    A: From the machine that didn't originate the branch, fetch the branches from the existing remote and checkout that branch exclusively on the local machine:

    git fetch origin
git checkout -b <new_branch_name> origin/<remote_branch_name>

  • Q: How do I update my local branch with its corresponding remote branch?

    A: Always make sure your rebase when updating. Disregard the cli's suggestions since that aren't helpful here. Instead:

    git pull --rebase origin <feature_branch>:<feature_branch>