Contributing 🌈 Code with GitHub¶

There are oodles of great tutorials on various aspects of contributing to collaborative code projects with GitHub. This page is meant to provide a quick, recipe-like answer to the question "how do I contribute to the chromatic package?"

Should I submit an Issue to the chromatic GitHub repository?¶

Yes! You tried out chromatic and maybe thought it had some neat features, but you encountered something that didn't work quite how you expected it to, a question that you couldn't find an answer to in the documentation, or a feature that you wished existed. Those would all be great motivations to go to the chromatic GitHub repository to submit an Issue!

But...we know you! You're saying to yourself "Oh, gosh, they have their hands full, I don't want to bother them right now. I'm sure I'm the only one having this problem or with this question about how chromatic works. My idea probably matters only to me and not anyone else. I don't want to make more workf for other folks." You're wringing your hands and anxiously worrying about about whether to submit an Issue.

Still, can we please encourage you share your problem, ask your question, or make your suggestion? Your experience and curiosity and creativity would be extremely valuable contributions to the package, and make it better for everyone. It's super exciting to hear that someone new else trying to use this code package, and every bit of discussion about how to improve it is super helpful. I promise we're very friendly! So, please, hop on over and submit an Issue!

How do we get started with git and GitHub?¶

Yay! You're interested in contributing some code to the chromatic package. The first step will be to make sure you have a basic familiarity with git and GitHub as tools for safe and collaborative coding.

Christina Hedges has written some great resources on coding-related workflows for astronomy, including a tutorial for getting started with git and GitHub that you can watch here. If you're entirely new to these tools, please work through her tutorial and then come back here. If you haven't created one yet, make yourself a GitHub account

How do we contribute new code?¶

Because we have more than one person working on chromatic code, let's please use separate git branches for developing new features. Using branches allows us to write code in parallel and merge it together later, without constantly having to make sure that everything everybody writes is up-to-date everywhere all at once. We're generally trying to follow something like the Gitflow Workflow, to allow us to make changes to the shared code that are a little bit buffered from the published code used by non-developers.

There three branches you should know about, and only two you should probably interact with:

• The main branch hosts the published version of the code for public users. New pip versions of the code will be released from the main branch. Most developers should never interact directly with the main branch.
• The develop branch is the active branch for shared development. New feature branches should be created from the develop branch and once they're reviewed be merged back into develop. Occasionally, and only after careful testing and documentation edits, the develop branch will get merged into the main branch and published to pip.
• Your add-amazing-awesome-new-feature branch (where you replace the name with something more specific and informative) is a temporary branch that you created off of develop to add your amazing awesome new feature. You should make your changes and commits to that branch, and when you're ready to discuss to your contribution (either as a draft or a mostly finished product), you should submit a Pull Request from this feature branch into the develop branch. Features should be tested well enough that they won't break develop when they get merged into it (but if they do, possibly due to a temporary conflict with another feature branch, it's OK because the main branch is still safe). Once it's merged, your feature branch will be deleted, and you can start a new one to add a different new feature.

With these branches, here's what writing some new code for chromatic might look like for you. The following describes using git from the Terminal prompt. In practice, you might interact with git mostly through atom, GitHub Desktop, or some other tool.

1. Discuss your plans in an Issue. You might start from trying to address an existing issue, or you might add a new issue of your own. Either way, it's really helpful to let other folks know "here's what I'm trying to do" to avoid duplicate or unfocused efforts. If you're not already a Collaborator on the chromatic repository, we can add you at this point!
2. Use the Installation instructions to compelete the Developer Installation. This will download the develop branch of the chromatic repository onto your computer and set up your environment to point to the repository's directory.

git clone https://github.com/zkbt/chromatic.git
cd chromatic
pip install -e '.[develop]'

1. Create a new feature branch off of develop. Check out that branch, so that all commits you make will be associated with that branch.

git checkout develop
git branch add-amazing-awesome-new-feature
git checkout add-amazing-awesome-new-feature

1. Write your code. Follow some of the tips for Designing New 🌈 Features to get started, to make sure it imports correctly, and to write some useful tests. Once you've saved some changes to the code, commit those changes to your feature branch. (You can confirm you're on your feature branch by running git branch and seeing which branch has the *.)

git add .
git commit -m "{include informative commit message here}"

Up to this point, whatever changes you have committed are still only stored on your computer.

1. To start sharing your new code, push your branch up to GitHub. The first time you run this push command, you'll probably get some instructions about how to link your local branch to a new remote one that you're about to create; follow them.

git push

Now your branch and most recently pushed commits should appear in the GitHub list of branches.

1. To ask for your code to be reviewed, either because you think it's finished or because you've completed enough of a draft to be useful to start discussing, submit a Pull Request asking us to pull the code from your feature branch into develop. We'll probably discuss a few aspects of it and suggest some changes, which can be implemented by continuing to push new commits to your feature branch as long as the Pull Request is still open. Once it's tested and works and we're all happy with it, we'll merge the code into develop, from where it will eventually then be merged into the main branch and released in the latest pip version.
2. 🌈🎉🤩 Celebrate!

What kinds of files should we commit?¶

Every file change commit to the repository will be stored and able to be recovered in the future. That's great for being able to go back to previous versions in the code's history, but it means that the repository could very easily get very big if we include lots of large files in our commits. Large files are extra troublesome if they change frequently, because then we're storing a new copy of every large file in our repository.

Let's try to keep the chromatic repository relatively slim. To do that, please:

• Avoid committing large data, image, or movie files to the repository. If you think you need to include a large file (anything over ~1 MB), raise an Issue to discuss your plans. There might be a better alternative.
• Avoid committing scratch jupyter notebook files where you're testing out new code. The only notebooks that should be committed to chromatic are ones meant to serve as public documentation; those should be stored in the docs/ folder as described in Writing 🌈 Documentation and their outputs should be cleared before saving.

Wait, I have a question that's not answered here!¶

This page is a whirlwind tour! We probably missed lots of important information. If you have a question, no matter how small or large or seemingly basic, please ask Zach or submit an Issue.