|
1 | | -# Contributing |
| 1 | +# Contributing to FitLins |
2 | 2 |
|
3 | | -**Are you new to open source and GitHub?** |
4 | | -If so, reading the "[How to submit a contribution]( |
5 | | -https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution)" |
6 | | -guide will provide a great introduction to contributing to MODELFIT and other |
7 | | -Open Source projects. |
8 | | -All the MODELFIT-specific contributing instructions listed below will make much |
9 | | -more sense after reading this guide. |
| 3 | +Welcome to the FitLins repository! |
| 4 | +We're excited you're here and want to contribute. |
10 | 5 |
|
11 | | -If you are new to the project don't forget to add your name and affiliation to |
12 | | -the `.zenodo.json` file. |
| 6 | +## Practical guide to submitting your contribution |
13 | 7 |
|
14 | | -## Code style guide |
| 8 | +These guidelines are designed to make it as easy as possible to get involved. |
| 9 | +If you have any questions that aren't discussed below, |
| 10 | +please let us know by opening an [issue][link_issues]! |
15 | 11 |
|
16 | | -### Function and variable names |
| 12 | +Before you start you'll need to set up a free [GitHub][link_github] account and sign in. |
| 13 | +Here are some [instructions][link_signupinstructions]. |
| 14 | + |
| 15 | +Already know what you're looking for in this guide? Jump to the following sections: |
| 16 | + |
| 17 | +* [Joining the conversation](#joining-the-conversation) |
| 18 | +* [Contributing through Github](#contributing-through-github) |
| 19 | +* [Understanding issues](#understanding-issues) |
| 20 | +* [Making a change](#making-a-change) |
| 21 | +* [Structuring contributions](#FitLins-coding-style-guide) |
| 22 | +* [Licensing](#licensing) |
| 23 | +* [Recognizing contributors](#recognizing-contributions) |
| 24 | + |
| 25 | + |
| 26 | +## Joining the conversation |
| 27 | + |
| 28 | +FitLins is maintained by a growing group of enthusiastic developers— |
| 29 | +and we're excited to have you join! |
| 30 | +Most of our discussions will take place on open [issues][link_issues]. |
| 31 | + |
| 32 | +We also encourage users to report any difficulties they encounter on [NeuroStars][link_stars], |
| 33 | +a community platform for discussing neuroimaging. |
| 34 | + |
| 35 | +We actively monitor both spaces and look forward to hearing from you in either venue! |
| 36 | + |
| 37 | + |
| 38 | +## Contributing through GitHub |
| 39 | + |
| 40 | +[git][link_git] is a really useful tool for version control. |
| 41 | +[GitHub][link_github] sits on top of git and supports collaborative and distributed working. |
| 42 | + |
| 43 | +If you're not yet familiar with `git`, there are lots of great resources to help you *git* started! |
| 44 | +Some of our favorites include the [git Handbook][link_handbook] and |
| 45 | +the [Software Carpentry introduction to git][link_swc_intro]. |
| 46 | + |
| 47 | +On GitHub, You'll use [Markdown][markdown] to chat in issues and pull requests. |
| 48 | +You can think of Markdown as a few little symbols around your text that will allow GitHub |
| 49 | +to render the text with a little bit of formatting. |
| 50 | +For example you could write words as bold (`**bold**`), or in italics (`*italics*`), |
| 51 | +or as a [link][rick_roll] (`[link](https://https://youtu.be/dQw4w9WgXcQ)`) to another webpage. |
| 52 | + |
| 53 | +GitHub has a really helpful page for getting started with |
| 54 | +[writing and formatting Markdown on GitHub][writing_formatting_github]. |
| 55 | + |
| 56 | + |
| 57 | +## Understanding issues |
| 58 | + |
| 59 | +Every project on GitHub uses [issues][link_issues] slightly differently. |
| 60 | + |
| 61 | +The following outlines how the FitLins developers think about these tools. |
| 62 | + |
| 63 | +* **Issues** are individual pieces of work that need to be completed to move the project forwards. |
| 64 | +A general guideline: if you find yourself tempted to write a great big issue that |
| 65 | +is difficult to describe as one unit of work, please consider splitting it into two or more issues. |
| 66 | + |
| 67 | + Issues are assigned [labels](#issue-labels) which explain how they relate to the overall project's |
| 68 | + goals and immediate next steps. |
| 69 | + |
| 70 | + |
| 71 | +### Issue Labels |
| 72 | + |
| 73 | +The current list of issue labels are [here][link_labels] and include: |
| 74 | + |
| 75 | +* [][link_helpwanted] *These issues contain a task that a member of the team has determined we need additional help with.* |
| 76 | + |
| 77 | + If you feel that you can contribute to one of these issues, |
| 78 | + we especially encourage you to do so! |
| 79 | + |
| 80 | +* [][link_bugs] *These issues point to problems in the project.* |
| 81 | + |
| 82 | + If you find new a bug, please give as much detail as possible in your issue, |
| 83 | + including steps to recreate the error. |
| 84 | + If you experience the same bug as one already listed, |
| 85 | + please add any additional information that you have as a comment. |
| 86 | + |
| 87 | +* [][link_feature] *These issues are asking for new features to be added to the project.* |
| 88 | + |
| 89 | + Please try to make sure that your requested feature is distinct from any others |
| 90 | + that have already been requested or implemented. |
| 91 | + If you find one that's similar but there are subtle differences, |
| 92 | + please reference the other request in your issue. |
| 93 | + |
| 94 | + |
| 95 | +## Making a change |
| 96 | + |
| 97 | +We appreciate all contributions to FitLins, |
| 98 | +but those accepted fastest will follow a workflow similar to the following: |
| 99 | + |
| 100 | +**1. Comment on an existing issue or open a new issue referencing your addition.** |
| 101 | + |
| 102 | +This allows other members of the FitLins development team to confirm that you aren't |
| 103 | +overlapping with work that's currently underway and that everyone is on the same page |
| 104 | +with the goal of the work you're going to carry out. |
| 105 | + |
| 106 | +[This blog][link_pushpullblog] is a nice explanation of why putting this work in up front |
| 107 | +is so useful to everyone involved. |
| 108 | + |
| 109 | +**2. [Fork][link_fork] the [FitLins repository][link_FitLins] to your profile.** |
| 110 | + |
| 111 | +This is now your own unique copy of FitLins. |
| 112 | +Changes here won't effect anyone else's work, so it's a safe space to explore edits to the code! |
| 113 | + |
| 114 | +Make sure to [keep your fork up to date][link_updateupstreamwiki] with the master repository. |
| 115 | + |
| 116 | +**3. Make the changes you've discussed, following the [FitLins coding style guide](#FitLins-coding-style-guide).** |
| 117 | + |
| 118 | +Try to keep the changes focused. |
| 119 | +If you feel tempted to "branch out" then please make a [new branch][link_branches]. |
| 120 | + |
| 121 | +**4. Submit a [pull request][link_pullrequest].** |
| 122 | + |
| 123 | +A member of the development team will review your changes to confirm |
| 124 | +that they can be merged into the main code base. |
| 125 | + |
| 126 | +Pull requests titles should begin with a descriptive prefix: |
| 127 | + |
| 128 | +* ``ENH``: enhancements or new features |
| 129 | +* ``FIX``: bug fixes |
| 130 | +* ``TST``: new or updated tests |
| 131 | +* ``DOC``: new or updated documentation |
| 132 | +* ``STY``: style changes |
| 133 | +* ``REF``: refactoring existing code |
| 134 | +* ``CI``: updates to continous integration infrastructure |
| 135 | +* ``MAINT``: general maintenance |
| 136 | + |
| 137 | +For example: `[ENH] Support for naive thresholding` |
| 138 | + |
| 139 | +For works-in-progress, add the ``WIP`` tag in addition to the descriptive prefix. |
| 140 | +Pull-requests tagged with ``[WIP]`` will not be merged until the tag is removed. |
| 141 | + |
| 142 | +## FitLins coding style guide |
17 | 143 |
|
18 | 144 | Whenever possible, instances of Nodes and Workflows should use the same names |
19 | 145 | as the variables they are assigned to. |
@@ -56,3 +182,56 @@ myworkflow1_wf = init_workflow_wf(name='myworkflow1_wf') |
56 | 182 | myworkflow_lh_wf = init_workflow_wf(name='myworkflow_lh_wf') |
57 | 183 | myworkflow_rh_wf = init_workflow_wf(name='myworkflow_rh_wf') |
58 | 184 | ``` |
| 185 | + |
| 186 | + |
| 187 | +## Licensing |
| 188 | + |
| 189 | +FitLins is licensed under the [Apache License, 2.0][link_license]. |
| 190 | +By contributing to FitLins, |
| 191 | +you acknowledge that any contributions will be licensed under the same terms. |
| 192 | + |
| 193 | + |
| 194 | +## Recognizing contributions |
| 195 | + |
| 196 | +We welcome and recognize all contributions from documentation to testing to code development. |
| 197 | +You can see a list of current contributors in our [zenodo file][link_zenodo]. |
| 198 | +If you are new to the project, don't forget to add your name and affiliation there! |
| 199 | + |
| 200 | +## Thank you! |
| 201 | + |
| 202 | +You're awesome. :wave::smiley: |
| 203 | + |
| 204 | +<br> |
| 205 | + |
| 206 | +*— Based on contributing guidelines from the [STEMMRoleModels][link_stemmrolemodels] project.* |
| 207 | + |
| 208 | +[link_github]: https://github.com/ |
| 209 | +[link_FitLins]: https://github.com/poldracklab/fitlins |
| 210 | +[link_signupinstructions]: https://help.github.com/articles/signing-up-for-a-new-github-account |
| 211 | + |
| 212 | +[link_stars]: https://neurostars.org/ |
| 213 | + |
| 214 | +[link_git]: https://git-scm.com/ |
| 215 | +[link_handbook]: https://guides.github.com/introduction/git-handbook/ |
| 216 | +[link_swc_intro]: http://swcarpentry.github.io/git-novice/ |
| 217 | + |
| 218 | +[writing_formatting_github]: https://help.github.com/articles/getting-started-with-writing-and-formatting-on-github |
| 219 | +[markdown]: https://daringfireball.net/projects/markdown |
| 220 | +[rick_roll]: https://www.youtube.com/watch?v=dQw4w9WgXcQ |
| 221 | + |
| 222 | +[link_issues]: https://github.com/poldracklab/fitlins/issues |
| 223 | +[link_labels]: https://github.com/poldracklab/fitlins/labels |
| 224 | +[link_discussingissues]: https://help.github.com/articles/discussing-projects-in-issues-and-pull-requests |
| 225 | + |
| 226 | +[link_bugs]: https://github.com/poldracklab/fitlins/labels/bug |
| 227 | +[link_helpwanted]: https://github.com/poldracklab/fitlins/labels/help%20wanted |
| 228 | +[link_feature]: https://github.com/poldracklab/fitlins/labels/feature |
| 229 | + |
| 230 | +[link_pullrequest]: https://help.github.com/articles/creating-a-pull-request/ |
| 231 | +[link_fork]: https://help.github.com/articles/fork-a-repo/ |
| 232 | +[link_pushpullblog]: https://www.igvita.com/2011/12/19/dont-push-your-pull-requests/ |
| 233 | +[link_branches]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/ |
| 234 | +[link_updateupstreamwiki]: https://help.github.com/articles/syncing-a-fork/ |
| 235 | +[link_stemmrolemodels]: https://github.com/KirstieJane/STEMMRoleModels |
| 236 | +[link_zenodo]: https://github.com/poldracklab/fitlins/blob/master/.zenodo.json |
| 237 | +[link_license]: https://github.com/poldracklab/fitlins/blob/master/LICENSE |
0 commit comments