Contributing Guide

So you’re interested in making your first open source contribution to STUMPY? We’re excited to start this journey with you. Here are some things that will help you get started.

Git and GitHub

You don’t need a GitHub account to use STUMPY, but you do if you want to make a code or documentation contribution. This account will enable you to contribute to many of the most popular open source projects. Additionally, it will give you a place to store, track, and coordinate progress on your own projects. GitHub is a remote repository for the version control system git. Git is a tool that tracks changes in projects by constructing a directed acyclic graph (fancy way of allowing us to create branches, revert changes, and identify conflicts). You use git on your local machine, but when you want to save your work or collaborate with other team members, you push your work to a remote repository. In this case, that remote will be GitHub.

With all of that in mind, you’ll also need to install git.

Warning: Don’t confuse git and GitHub. Git is a tool used for version control. GitHub is an online platform used as a remote repository for git projects.
Checklist:
[ ] Create GitHub account
[ ] Install Git

Find your contribution

You’ve decided that you want to contribute, but how do you approach a new project and figure out where you can help? This will feel like like trying to jump into a conversation that’s been happening for months (or years) and can often be intimidating. If you’ve used the project before, you’ll be more familiar with its structure and API, but you probably haven’t “peeked behind the curtain” before. The best place to get started is the list of Issues. These are requests/changes/bugs that other people have identified. Feel free to peruse the list to get a feel for all of the work ongoing in the project. Often, maintainers will have a label system to organize the issues. These labels may include things like documentation or enhancement. For new contributors, many projects have a good first issue label.

Your next stop (if it exists), should always be CONTRIBUTING.md. Here, the maintainers outline any guidance they have for contributors,

If you click on any issue, you’ll see a running history of chats. This serves as the record of thoughts around that specific issue. For some issues, you may see an ongoing conversation. In others, you may just see the initial issue. This is your chance to have a dialogue with the maintainers. If you’ve found an open issue that interests you and you think you may be able to solve, feel free to leave a message. Remember that maintainers are people too and at STUMPY, they’re excited to help new contributors. Here’s an example of a potential message:

First time contributor here! I see that this issue is related to a bug caused by a collision in two variable names here and here. Does that seem right to you? If so, I’d like to take this issue and submit a pull request.

This message does a couple of things. It shows that you’ve done a little bit of research into the issue (demonstrates respect for the maintainers’ time), gets their input (helps you solve the problem) and makes sure they will accept a pull request (saves your time/effort). Remember how you’re jumping into an ongoing conversation? Sometimes an issue will become irrelevant or obsolete based on changes happening somewhere else in the package. A quick note like this lets the maintainer know that you’re going to work on this issue and confirms that it is still a valuable issue.

Warning: If you can tell someone else is actively working on an issue, don’t take it.
Checklist:
[ ] Identify an issue
[ ] Read CONTRIBUTING.md
[ ] Post your proposal in the issue

Setup your Branch

Okay, so you’ve picked an issue and the maintainers are excited to have your help. Now, let’s get to work!

First, you need to create copy of the repository for you to work off of; this is called a fork. Here are instructions on forking a repository. Now you have your own copy associated with your GitHub account.

Next, you need to clone this copy of the repository. This simply downloads it to your computer so that you can work on it. Here are instructions on cloning a repository. Now you have a copy downloaded on your computer. *Remember to clone your fork, not STUMPY.

Next, you want to create a branch. Here’s an overview of how git branches work, but if you’re working in the command line, you probably just need to type git checkout -b branch_name. branch_name should be something descriptive about the change you are making like change_index_slice or document_x.

Now, any changes you make in the project will be reflected in your branch. Later, You’ll want your changes to be merged into the main STUMPY repository (so that everyone can enjoy your craftsmanship). Your branch reflects all of these changes.

Warning: Create your branch before making any changes.
Checklist:
[ ] Fork STUMPY to your own account
[ ] Clone a local copy
[ ] Create a branch for your work

Make your Changes

When working on a new project, there are often going to be dependencies. In order to isolate dependencies between different projects, it’s a good practice to use a virtual environment. STUMPY supports both venv and conda. After creating and activating either of these virtual environments, any dependencies you install will be isolated (so they don’t break anything else on your system).

Next, install the dependencies using the From Source Section of the instructions. A good check to make sure everything is working 100% is to run the unit tests. For STUMPY, we have scripts to help you do that. You’ll run ./setup.sh && ./test.sh. Ideally, you’ll see the excellent STUMPY test coverage passing. If things start failing or breaking, you have a dependency problem. There’s nothing worse than finding this out after you’ve made changes.

If all of the tests pass, you know that you have a working copy of STUMPY to start your development on. Go ahead and implement your feature or change!

Checklist:
[ ] Create a virtual environment
[ ] Install dependencies
[ ] Run the unit tests

Adhere to CONTRIBUTING.md Guidance

One of the great benefits of open source is the ability to collaborate with developers from around the world. However, you can imagine that combining their contributions into one coherent codebase while maintaining consistency can be challenging. Luckily, recent gains in automated tooling have made this a lot easier. Remember CONTRIBUTING.md? There are a couple of things we want to make sure we do before we submit a pull request.

First, if you implemented a new feature or changed an existing feature, you are also responsible for providing the unit test. This can often be just as much work as the feature, so make sure you account for it.

Next, run flake8 and black. flake8 is a linter that checks the style and quality of the code. black makes any necessary changes to ensure consistent code format.

Checklist:
[ ] Write/update any unit tests
[ ] Run black to reformat any python files you changed
[ ] Run flake8 to identify any formatting errors before you submit your pull request
[ ] Run the unit tests. In STUMPY, you’ll run ./setup.sh && ./tests.sh

Push your code to GitHub

Now your fork contains updated code and unit tests that adhere to the STUMPY formatting standards. If you’re comfortable with git or have been doing work between multiple workstations, you may have pushed your commits to GitHub already. If not, now is the time!

When you were working on your change, you probably saved your files all the time. Those changes were saved on your local machine, but never updated in version control. To do that, you’ll need to git add <files> (“hey git, please track these files”), git commit -m <message> (“hey git, at this point, I want to save”) and git push (“Hey git, take the last commit and move it to GitHub”) as described here. Remember to write a good commit message.

Warning: If this is your first time using git, it may through a warning about global settings. Luckily, that warning tells you exactly how to fix it.
Checklist:
[ ] git add your_file
[ ] git commit -m 'Great Commit Message'
[ ] git push

Create a Pull Request

Now, your updated code is on GitHub in your fork of STUMPY. If you want the STUMPY maintainers to see it, you need to create a Pull Request. There are instructions here, but github is also pretty smart. If you navigate to your fork of the repository shortly after you push a commit, you’ll often see a message like “Your recently pushed branches: X “. Clicking that will automatically create your pull request. Like a commit, make sure to give it a descriptive name. If your change isn’t quite working yet, you can preface your pull request with [WIP] which stands for “Work in Progress.” In the body of your Pull Request, reference the Issue Number that you’re working on. GitHub will automatically link your pull request to that issue. This just makes housekeeping easier.

Here’s your next chance to communicate with the maintainers. Let them know what changes you made and if you need any help. This pull request will now be the running dialogue between you and the maintainers as you work on the issue.

Continuous integration systems automatically determine the suitability of merging pull requests. They check the formatting, test coverage, and test success of your code. After you submit a pull request, you’ll see these running (as comments in your pull request). If they fail, your code will not be merged until the failure is fixed. In STUMPY, locally passing flake8, black, and ./setup.sh && ./tests.sh should ensure your continuous integration tests pass.

Checklist:
[ ] Create a Pull Request
[ ] Write an informative Pull Request Message
[ ] Monitor your Pull Request for continuous integration checks and messages from the maintainers

Work on your Pull Request

It is extremely likely that the maintainer will have questions, comments, or suggestions on your pull request. This is an opportunity for collaboration and should benefit both parties. Continue refining your contribution based on their feedback. Now, every commit you make will automatically be refected in this pull request; there’s no need to create another. After you make any change in your local code, just add, commit, and push like before.

Warning: After every change, make sure to run your formatting checks and unit tests.
Checklist:
[ ] Be open minded, responsive, and polite

Merge!

When the contribution is nice and polished, the maintainers will merge it into STUMPY. Success!

Checklist:
[ ] Celebrate
[ ] Go find another issue

What to do when it goes wrong

Invariably, something goes wrong. Remember, you’re not in this alone. The open source community is a community and we appreciate your interest and contribution to STUMPY. If your barrier is related to an issue already filed in GitHub, that issue probably a great place to request additional information and help. If your barrier is related to your solution to an issue, go ahead and submit your progress as a pull request. As always, be polite and be patient.

Final Checklist:

[ ] Create GitHub account
[ ] Install Git
[ ] Identify an issue
[ ] Read CONTRIBUTING.md
[ ] Post your proposal in the issue
[ ] Fork STUMPY to your own account
[ ] Clone a local copy
[ ] Create a branch for your work
[ ] Create a virtual environment
[ ] Install dependencies
[ ] Run the unit tests
[ ] Write/update any unit tests
[ ] Run black to reformat any python files you changed
[ ] Run flake8 to identify any formatting errors before you submit your pull request
[ ] Run the unit tests. In STUMPY, you’ll run ./setup.sh && ./tests.sh
[ ] git add your_file
[ ] git commit -m 'Great Commit Message'
[ ] git push
[ ] Create a Pull Request
[ ] Write an informative Pull Request Message
[ ] Monitor your Pull Request for continuous integration checks and messages from the maintainers
[ ] Be open minded, responsive, and polite
[ ] Celebrate
[ ] Go find another issue