Welcome to the abagen repository!
We're so excited you're here and want to contribute.
The point of this guide is to welcome new users and contributors to abagen.
We hope that these guidelines are designed to make it as easy as possible to get involved.
We welcome all contributions and would love it if you could follow these guidelines to make sure your contributions can be easily integrated!
That said, please don't let the perfect be the enemy of the good—any contributions are worth making, even if you don't follow the process detailed below to a T.
If you have any questions that aren't discussed below, please let us know by opening an issue!
Been here before? Already know what you're looking for in this guide? Jump to the following sections:
- Joining the community
- Contributing through Github
- Where to start: GitHub Issues
- Making a change with a pull request
- Style guide
- Recognizing contributions
We requires that all interactions that take place on the abagen repository adhere to our Code of Conduct.
Git is a really useful tool for version control. GitHub sits on top of Git and supports collaborative and distributed working.
We know that it can be daunting to start using Git and GitHub if you haven't worked with them in the past, but abagen maintainers are here to help you figure out any of the jargon or confusing instructions you encounter! ❤️
In order to contribute to abagen you'll need to set up a free GitHub account and sign in.
You can follow these instructions to help you get going, but please ask us any questions you might need along the way.
Once you have an account you'll have to use Markdown to chat in issues and pull requests on GitHub.
You can think of Markdown as a few little symbols around your text that will allow GitHub to render the text with a little bit of formatting.
For example you could write words as bold (**bold**), or in italics (*italics*), or as a link ([link](https://google.com)) to another webpage.
GitHub has a helpful page on getting started with writing and formatting Markdown on GitHub.
Communication on abagen primarily happens through discussion on our issues and pull request.
Before you open a new issue, please check if any of our open issues cover your idea already!
The current list of labels can be found here and includes:
-
These issues are great ways to get started contributing.
If you are interested in getting involved in
abagenthen these are good places to start! The maintainers will be happy to walk you through the contribution process step-by-step. Please note: if you're a seasoned contributor we would appreciate if you could select a different issue to work from to keep these available for newer and potentially more anxious team members! -
These issues contain a task that a member of the team has determined we need additional help with.
If you feel that you can contribute to one of these issues, we especially encourage you to do so.
-
These issues point to problems in the project.
If you find new a bug, please give as much detail as possible in your issue, including steps to recreate the error. If you experience the same bug as one already listed please add any additional information that you have as a comment on the issue.
-
These issues relate to updating documentation.
This is used to highlight when something is missing from or unclear in the current documentation.
-
These issues are open-ended and don't necessarily have a definite solution.
If you're unclear about something in repository or the related documentation and simply need to ask a clarifying question, this is the label for you! This can also be paired with other labels (e.g., enhancement, refactor) on issues when the means by which to resolve the issue is unclear and warrants discussion.
-
These issues suggest new features that can be added to the project.
If you want to ask for something new please try to make sure that your request is distinct from any others that are already in the queue. If you find another issue requesting an enhancement that is similar to your suggestion but still distinct please reference the related enhancement in your issue.
-
These issues relate to general package management
Does a dependency need to be pinned? Is a link not resolving anymore? These issues address when there's a change, update, or modification that needs to be made to the package that doesn't necessarily impact anything other besides managing
abagen. -
These issues address changes that need to be made
If you're suggesting a modification that isn't a bug or enhancement, but rather a change to the existing code designed to make it more accessible/understandable, this label may be appropriate. While refactoring often does significantly enhance the code, we reserve the enhacement label for new features.
-
These issues are pressing and need to be addressed urgently
This label will likely be added by an
abagenteam member to highlight critical bugs or updates that need to be made. -
These issues relate to code testing
We appreciate all contributions to abagen!
Thank you so much for helping us build this exciting tool.
The following steps serve as a guide to help you contribute in a way that will make it easy for you and the abagen team members to get your changes merged quickly and efficiently!
This allows other members of the abagen development team to confirm that you aren't overlapping with work that's currently underway and that everyone is on the same page with the goal of the work you're going to carry out.
This blog is a nice explanation of why putting this work in up front is so useful to everyone involved.
2. Fork the abagen repository to your profile
This is now your own unique copy of abagen.
Changes here won't effect anyone else's work, so it's a safe space to make edits to the code.
If you will be making changes on your local machine, remember to clone your fork of abagen.
Make sure to keep your fork up to date with the master repository, otherwise you can end up with lots of dreaded merge conflicts! 😬
To test a change you may need to install the copy of abagen that you cloned to your local machine.
To do so, change into the abagen directory and run:
pip install -e .[all]This should ensure that when you open Python and type import abagen you are using the version of the code that you're editing!
(But note that if you make changes to the code after you've run import abagen you may need to close Python and re-open a new instance for the changes to take effect.)
Before you being making changes please make sure you review the abagen style conventions!
Try to keep your changes focused. If you submit a large amount of work all in one go it will be much more work for whomever is reviewing your pull request!
We've found that working on a new branch for each Issue makes it easier to keep your changes targeted. Using a new branch allows you to follow the "standard" GitHub workflow when making changes. This blog details different Git branching models.
While making your changes, commit often and write good, detailed commit messages. This blog explains how to write a good Git commit message and why it matters. It is also perfectly fine to have a lot of commits—including ones that break code! If you are temporarily breaking things locally a good rule is to only push your changes to GitHub once your tests are passing!
Although abagen is set up with continuous integration (CI) testing, it's always good to test your changes locally, too!
If you're making modifications to the Python code in abagen you can test your changes with the following command:
pytest --doctest-modules abagenThis may take a while to run, but it should give you a detailed output of what tests are being run and what errors, if any, were generated.
This command is run by the CI tests when you open a PR, so if you're stumped by an error message feel free to push your changes to GitHub and make a PR to ask the abagen team for help!
If you're making changes to documentation we suggest rendering the HTML files locally in order to review your edits. You can do this with the following command:
make clean htmlwhich should be run from the docs/ directory in your local abagen repository.
Once this finishes you can fire up a web browser and open the abagen/docs/_build/html/index.html file to investigate how the documentation looks with your modifications.
6. Submit a pull request
Before submitting your pull request please make sure you review the abagen pull request style guide!
We encourage you to open a pull request as early in your contributing process as possible. This allows everyone to see what is currently being worked on. It also provides you, the contributor, feedback in real time from both the community and the continuous integration tests as you make commits (which will help prevent stuff from breaking!).
If you have opened the pull request early and know that its contents are not ready for review or to be merged, please mark it as ["draft" pull request][link_draftprs]. When you are happy with it and are ready for it to be merged into the main repository please mark it as "Ready for review". When you mark a pull request ready for review please make sure that you also check the box to allow edits from maintainers.
A member of the abagen team will then review your changes to confirm that they can be merged into the main repository.
A review will probably consist of a few questions to help clarify the work you've done.
Keep an eye on your GitHub notifications and be prepared to join in that conversation.
If a team member requests modifications to your changes you can continue editing your local copy of the repository and push the new changes back up to your fork. The pull request you created from your fork will be automatically updated—no need to create a new pull request when you make a change in response to reviews!
Sometimes team members will "suggest" changes to the code using GitHub's built-in suggestion feature. In that case you can automatically incorporate the suggested changes directly from Github!
After successful merging of the pull request, remember to keep your fork up to date with the master abagen repository.
What happens if the continuous integration (CI) tests fails (that is, if the pull request notifies you that "Some checks were not successful")?
The CI can fail for any number of reasons.
At the bottom of the pull request where it says whether your build passed or failed you can click “Details” next to the test.
This will automatically open the TravisCI website which details all the builds that were run for your pull request.
You can view the log for the CI test builds which will often provide the exact error that caused the failure.
Sometimes failures are stochastic and simply need to be re-run; if you think this is the case please notify someone on the abagen team and they will trigger a "rebuild!"
Generally, team members won't conduct reviews of pull requests (even if they are marked as "ready for review") until the CI tests are all passing. However, if you have any questions about your pull request before the tests are passing or if you are confused about why your tests are failing, please reach out and ask us about it!
To ensure some consistency in the abagen Python codebase we have a few style conventions.
All code should follow the PEP8 conventions, whenever possible.
Importantly, we abide by a strict 79-character line length maximum.
You can check that your code follows these conventions by running flake8 abagen from inside the local copy of your abagen repository.
The CI tests will error and your pull request will not be merged if your code fails to follow these conventions.
When writing new functions or classes please make sure you include doc-strings (even if they are internal functions/classes!).
Doc-strings should follow the numpydoc conventions.
In general we encourage extensive documentation and code comments for all contributions to abagen!
Besides this document and the Code of Conduct, all documentation for abagen is written using reStructuredText (RST).
You can tell whether a file is written in reStructuredText by checking for the the ".rst" suffix.
Writing our documentation in RST allows us to use the [Sphinx] documentation generator and host our documentation on ReadTheDocs, allowing an easily accessible way to access abagen documentation.
While using RST can be a bit confusing at first, there are lots of fantastic resources for learning how to use it. We especially like this walkthrough, but other good guides include this primer and this quick reference. If you have any questions as you make edits to the documentation please don't hesitate to ask!
To improve understanding of pull requests "at a glance", we encourage the use of several standardized tags. When opening a pull request, please use at least one of the following prefixes in the title of the pull request:
- [BRK] for changes which break existing builds or tests
- [DOC] for new or updated documentation
- [ENH] for enhancements
- [FIX] for bug fixes
- [REF] for refactoring existing code
- [STY] for stylistic changes
- [TST] for new or updated tests, and
You can also combine the tags! If you are updating both a test and some related documentation, you could use [TST, DOC]. Feel free to look at our closed pull requests for examples of good titles!
The body of the pull request should first describe what issue(s) the pull request addresses using GitHub's pull request keywords (for example, "Closes #12" or "Fixes #13").
The remainder of the pull request body should explain what changes are being made and if there are any things you would like an abagen team member to concentrate on with their feedback during their review.
We welcome and recognize all contributions to abagen from documentation to testing to code development to participating in discussion on Issues and PRs!
You can see a list of our current contributors in the contributors tab.
These Contributing Guidelines have been adapted from the contributing guidelines of The Turing Way and tedana. (License: CC-BY)