Skip to content

contributing

Jump to bottom
markcerv edited this page Feb 5, 2025 · 2 revisions

Contributing code to the project

Let's walk through a typical workflow for contributing to this project

Basic steps

Visit the Intentional Walk Server - Issues page and find an issue that you want to work on.

  • Make sure your code is up-to-date
  • Create a new branch off of master
  • Commit your changes
  • Push up the branch to Github
  • Create the pull request on the Github website.

Step by Step

Get the latest code

# Fetch the latest code changes
git fetch origin master

# Check to see if there are any changes that you don't have
git log ..FETCH_HEAD

# If there is no output, you are up-to-date
# If there is output, it will show you all of the commits that your local repo does NOT have

# If you want to see what actual files have changed in the above commits, execute this command:
git log --stat ..FETCH_HEAD

# To merge in the code, execute this command:
git merge FETCH_HEAD

Create a branch to work on

Naming tip: start the branch name with the issue number that you are fixing followed by a dash, then briefly describe your fix with lower case letters only and use dashes instead of spaces.

Sample branch name: 123-new-branch-name

Here's a quick way to create AND switch to a new branch (assuming you're currently on up-to-date master):

# Instead of 123-new-branch-name, use the correct name as described above in naming tip
git checkout -b 123-new-branch-name

Make your changes/code updates

Now comes the (hopefully) fun and rewarding part: doing the actual coding.

Go ahead and commit as often as you'd like inside of the branch that you are working on. Once you are done working on it and it's been submitted back to the repo, a Git Merge Squash will happen:

git merge --squash is a Git operation that allows you to take all the changes from one branch and squash them into a single commit on top of the branch you're currently on. This is different from a regular merge, where all commits from the feature branch are preserved. By squashing them into one, you're essentially saying, "Take all these changes as if they happened in a single moment." source

Test before pushing back to repo

Please make sure that your latest changes don't break anything and that they pass the test suite.

docker-compose stop
docker-compose build

# assuming it builds with no errors, fire it up again
docker-compose up

# In another terminal, get into the server's bash shell
docker-compose exec server bash -l

# run the pytest suite
pytest

If you get warnings, see if you can clean them up. If you have errors, do NOT go any further. Either fix your code, or update the test suite.

Pushing code back to repo

Confirm that you have the main github repo (and not your fork) as your origin remote: git remote -v

origin  https://github.com/sfbrigade/intentional-walk-server.git (fetch)
origin  https://github.com/sfbrigade/intentional-walk-server.git (push)

To push up a new branch:

  • git push -u origin 123-new-branch-name (don't actually use 123-new-branch-name, use YOUR branch name)

You should get a message that's similar to this:

$ git push -u origin 220-upgrade-postgres-in-docker
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 20 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 412 bytes | 34.00 KiB/s, done.
Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
remote: 
remote: Create a pull request for '220-upgrade-postgres-in-docker' on GitHub by visiting:
remote:      https://github.com/sfbrigade/intentional-walk-server/pull/new/220-upgrade-postgres-in-docker
remote: 
remote: GitHub found 1 vulnerability on sfbrigade/intentional-walk-server's default branch (1 moderate). To find out more, visit:
remote:      https://github.com/sfbrigade/intentional-walk-server/security/dependabot/175
remote: 
To https://github.com/sfbrigade/intentional-walk-server.git
 * [new branch]      220-upgrade-postgres-in-docker -> 220-upgrade-postgres-in-docker
Branch '220-upgrade-postgres-in-docker' set up to track remote branch '220-upgrade-postgres-in-docker' from 'origin'.

Pull Request

After pushing up your branch, you should have seen a message prompting you to create a pull request. You can either click on the URL that it showed you, or if you visit the pull requests page on our github page, you should see a prompt with your branch name, and a green button that says "Compare & pull request"

  • The title and description will get pulled in from the first few lines of your commit. Edit as needed (fix whitespace, check for typos, etc).
  • Assign a reviewer and assignee if known
  • Click on the [Create pull request] button

Review the Pull Request

Another developer will need to review your request.

(need to document the final steps)

(Please document the final steps)

Clone this wiki locally