From 8abcd931601869b486f6cf09eb11e7f4fed516ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Lespinasse?= Date: Fri, 13 Nov 2020 13:04:06 -0500 Subject: [PATCH 01/11] Conduct/contribut --- docs/community/CODE_OF_CONDUCT.md | 141 ++++++++ docs/community/CONTRIBUTING.md | 129 +++++++ docs/community/contributorfile.md | 569 ++++++++++++++++++++++++++++++ 3 files changed, 839 insertions(+) create mode 100644 docs/community/contributorfile.md diff --git a/docs/community/CODE_OF_CONDUCT.md b/docs/community/CODE_OF_CONDUCT.md index e69de29..ffc0ef4 100644 --- a/docs/community/CODE_OF_CONDUCT.md +++ b/docs/community/CODE_OF_CONDUCT.md @@ -0,0 +1,141 @@ +Physiopy Code of Conduct {#conduct} +======================== + +*Based on the* *Contributor Covenant Code of Conduct*\_. + +Our Pledge +---------- + +We as members, contributors, and leaders pledge to make participation in +our community a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +Our Standards +------------- + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our + mistakes, and learning from the experience +- Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or + advances of any kind +- Trolling, insulting or derogatory comments, and personal or + political attacks +- Public or private harassment +- Publishing others\' private information, such as a physical or email + address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in + a professional setting + +Enforcement Responsibilities +---------------------------- + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +Scope +----- + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include using an +official e-mail address, posting via an official social media account, +creating and diffusing outreaching material (e.g. abstracts, posters, +papers, demonstrations, ...), or acting as an appointed representative +at an online or offline event. + +Enforcement +----------- + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement at +`s.moia@bcbl.eu` All complaints will be reviewed and investigated +promptly and fairly. + +All community leaders are obligated to respect the privacy and security +of the reporter of any incident. + +Enforcement Guidelines +---------------------- + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. This includes avoiding interactions in community spaces as well as +external channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, +including sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No +public or private interaction with the people involved, including +unsolicited interaction with those enforcing the Code of Conduct, is +allowed during this period. Violating these terms may lead to a +permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +**Consequence**: A permanent ban from any sort of public interaction +within the project community. + +Attribution +----------- + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by Mozilla's code of conduct +enforcement ladder https://github.com/mozilla/diversity. + +For answers to common questions about this code of conduct, see the FAQ +at . Translations are +available at . diff --git a/docs/community/CONTRIBUTING.md b/docs/community/CONTRIBUTING.md index e69de29..9f83954 100644 --- a/docs/community/CONTRIBUTING.md +++ b/docs/community/CONTRIBUTING.md @@ -0,0 +1,129 @@ +Contributing to `physiopy` {#contributing} +========================== + +First of all: thank you! + +Contributions can be made in different ways, not only code! As we follow +the +[all-contributors](https://github.com/all-contributors/all-contributors) +specification, any contribution will be recognised accordingly. + +Follow these steps to get started: + +1. Have a look at the [contributor guide](contributorfile.html) page as + well as the [code of conduct](conduct.html). +2. Make sure that you have a GitHub account. You can set up a [free + GitHub account](https://github.com/); here are some + [instructions](https://help.github.com/articles/signing-up-for-a-new-github-account). +3. If you intend to contribute code and/or use the `physiopy` packages + in any way, check that you have `git` and `pip` installed on your + system. Then install `phys2bids` as a developer. This will let you + run the program with the latest modifications, without requiring to + re-install it every time. + +::: {.note} +::: {.admonition-title} +Note +::: + +The following instructions are provided assuming that python 3 is +**not** your default version of python. If it is, you might need to use +`pip` instead of `pip3`, although some OSs do adopt `pip3` anyway. If +you want to check, type `python --version` in a terminal. +::: + +Linux, Mac, and Windows developer installation +---------------------------------------------- + +Be sure to have `git` and `pip` installed. Fork the phys2bids repository +in GitHub, then open a terminal and run the following code to clone the +forked repository and set it as your \`origin\`: + + git clone https://github.com/{username}/phys2bids.git + # or in case you prefer to use ssh: + git clone git@github.com:{username}/phys2bids.git + +We also recommend to set up the physiopy/phys2bids repository as +`upstream`. In this way you can always keep your main branch +up to date with the command ``git pull upstream master``: + + cd phys2bids + git remote add upstream https://github.com/physiopy/phys2bids.git + git pull upstream master + + +### Basic installation + +If you use python frequently, or you are a python developer, chances are +that all the necessary dependencies are already installed in your +system. + +Move into the `phys2bids` folder and execute the command: + + pip3 install -e . + +### Full developer installation + +If it\'s your first experience as a python developer, or you just want +to be sure that you have everything you need to collaborate with us, you +can install `phys2bids` with all the other packages that we frequently +use during development in one step! + +Move into the `phys2bids` folder and execute the command: + + pip3 install -e .[all] + +This will install: + +> - `phys2bids` as an editable package, which means that you can +> modify the program and run it without having to reinstall it every +> time! +> - All `phys2bids` dependencies. +> - All **interface** modules, that deal with the interfaces for all +> the file formats. +> - All **style** modules, such as `flake8`, to help you linter the +> code! +> - All **documentation** modules, like `sphinx`, so that you can +> build the docs locally before submitting them. +> - All **test** modules, like `pytest`, in order for you to test your +> code locally before committing it! + +### Check your installation! + +Type the commands: + + cd phys2bids/tests + pytest + +This will execute the tests locally and check that your phys2bids +installation works properly. + + pytest + =================================== test session starts =================================== + platform win32 -- Python 3.8.6, pytest-6.1.1, py-1.9.0, pluggy-0.13.1 + rootdir: C:\Users\sento\phys2bids, configfile: setup.cfg + plugins: cov-2.10.1 + collected 61 items + + test_acq.py . [ 1%] + test_bids.py ................ [ 27%] + test_integration.py ... [ 32%] + test_phys2bids.py ... [ 37%] + test_physio_obj.py ....... [ 49%] + test_txt.py .................. [ 78%] + test_utils.py ........... [ 96%] + test_viz.py .x [100%] + + ================================= short test summary info ================================= + XFAIL test_viz.py::test_plot_trigger + ======================== 60 passed, 1 xfailed in 142.58s (0:02:22) ======================== + + +Do **not** worry if there is a xfail error in the log. This happens when +we know that a test will fail for known reasons, and we are probably +working to fix it (see +[here](https://docs.pytest.org/en/latest/skipping.html#xfail-mark-test-functions-as-expected-to-fail). +However, if you do encounter any other error, check that you have all +the extra dependencies installed and their version meets `phys2bids` +requirements. Contact us on +[gitter](https://gitter.im/physiopy/community) if you need help! diff --git a/docs/community/contributorfile.md b/docs/community/contributorfile.md new file mode 100644 index 0000000..10e5d55 --- /dev/null +++ b/docs/community/contributorfile.md @@ -0,0 +1,569 @@ +How to contribute to `physiopy` {#contributorfile} +=============================== + +Welcome to the `physiopy` organisation! It's great news that you're +thinking about contributing! + +Working with many people from many different places is great, but +sometimes this means that code can become messy due to the many +different ways a contribution can be made. For this reason, we have set +up some guidelines for contributions - to help you get involved ASAP! If +you lack knowledge in python development / github use / physiological +data handling, don't be scared! Try to jump in anyway. Most of the +original contributors learned these things exactly this way - jumping in +and hoping to fall in the right way without breaking too many bones. Do +you want to jump in but don't exactly know where/how? You can drop a few +lines in [gitter](https://gitter.im/phys2bids/community), so we can help +you find something that suits you! Already know what you\'re looking for +in this guide? Jump to the following sections: + +- [Aims of physiopy](#aims) +- [Join the conversation](#joinconvo) +- [Contributions](#contributiontypes) + - [Contributing with small documentation changes](#smalldocs) + - [Contributing with User testing](#usertests) + - [Contributing with test files](#testfile) + - [Contributing documentation through GitHub](#documenting) + - [Contributing code through GitHub](#code) + - [Contributing with Pull Requests Review](#reviews) +- [Issues and Milestones](#issuesmilestones) +- [Labels](#labeltypes) + - [Issues & PRs labels](#issueprlabels) + - [Issues labels](#issuelabel) + - [PRs labels](#prlabel) + - [Good First Issues](#g1i) +- [Contribution workflow](#workflow) +- [Pull Requests](#pr) +- [Reviewing PRs](#reviewing) +- [Style Guide](#styling) +- [Automatic Testing](#testing) +- [Recognizing contributors](#recognising) + +[Aims of `physiopy`](#aims) + + +`physiopy` is a **very** young project developed by a bunch of +researchers from the two different sides of the Atlantic Ocean (for +now). Our main goal is to help collect, analyse and share physiological +data, interfacing with (MRI) neuroimaging. We're trying to do so by: + +1. Writing packages to make a user-friendly pipeline to deal with + physiological data. +2. Writing packages that take into account the use of this + physiological data in combination with neuroimaging (MRI) analysis. +3. Providing documentation containing tips and strategies on how to + collect such data and use our packages. +4. Help set a standard for these data, albeit without forcing users to + use it. +5. Be an excuse for educational purposes on topics like Git/GitHub, + Python3, physiology and related tools/topics. + +[Joining the conversation](#joinconvo) +-------------------------------------- + +We're trying to keep all conversation related to project development in +GitHub [issues](https://github.com/physiopy/phys2bids/issues). We +maintain a [gitter chat room](https://gitter.im/physiopy/community) for +more informal conversations and general project updates. We also have a +dev call once a month - specifically the second Thursday of the month! +If you want to participate, drop a line in gitter! When interacting in +the common channels, please adhere to our [code of +conduct](conduct.html). + +[Contributions](#contributiontypes) +-------------------------------------- + +### Contributing with small documentation changes {#smalldocs} + +If you are new to GitHub and just have a small documentation change +recommendation (such as: typos detection, small improvements in the +content, ...), please open an issue in the relative project, and label +it with the "Documentation" label. Chances are those types of changes +are easily doable with GitHub\'s online editor, which means you can do +them, or ask for help from the developers! + +### Contributing with User testing {#usertests} + +Another, non-coding friendly way to contribute to `physiopy` is by +testing the packages. There are different kinds of tests, but to +simplify things you can think mainly about automatic tests and user +tests. To know more about **Automatic tests**, you can read the [testing +section](#testing). **User testing** are warm, human, emotional and +opinionated tests that not only check that the code is doing what it +needs to do, but also whether there's a better way to do it - namely +better reports, clearer screen outputs, warnings and exceptions, +unexpected bugs that have to be corrected. If you want to perform one, +open an issue on GitHub or drop a comment in Gitter, refer to this +[blueprint](https://docs.google.com/document/d/1b6wc7JVDs3vi-2IqGg_Ed_oWKbZ6siboAJHf55nodKo/edit?usp=sharing) +and don't be afraid to ask questions! + +### Contributing with test files {#testfile} + +At `physiopy` we always try to imagine and support every possible +setting out there. However, our imagination has a limit - but if you +think our packages should process a specific format/setting that you +have, we're more than glad to do so! To make it happen, we need an +example of the file we want to process, so you will have to share it +with us (and the rest of the world)! The contribution can be a full file +of data that you already acquired, a part of that file (pay attention to +what is the minimum you need to share!), or mock data. The file +contribution should come with a json file of the same name that contains +the necessary information to run `phys2bids` on that file contribution. +There is a [json blueprint in +OSF](https://mfr.de-1.osf.io/render?url=https://osf.io/jrnxv/?direct%26mode=render%26action=download%26mode=render), +you can download it and adapt it. Note that the frequency list **has to +be expressed in Hz** as an integer or float. To contribute with a test +file, open an Issue in GitHub and label it with *Test*. We'll help you +add the file in our [OSF](https://osf.io/3txqr/) space. We're extremely +grateful for this type of contribution - so grateful that we asked +allcontributors to add a dedicated category! + +### Contributing documentation through GitHub {#documenting} + +We use [readthedocs](https://readthedocs.org/) to create our +documentation. Every contribution is welcome and it follows the same +steps as a code contribution, explained below. + +### Contributing code through GitHub {#code} + +This section covers 90% of the contributions a project like `physiopy` +receives - code, documentation and tests. The best way to make this kind +of contribution, in a nutshell, is to: 1. Open an issue with the +intended modifications. 2. Label it, discuss it, (self-)assign it. 3. +Open a Pull Request (PR) to resolve the issue and label it. 4. Wait for +a review, discuss it or comply, repeat until ready. Issues and PR chats +are great to maintain track of the conversation on the contribution. +They are based upon GitHub-flavoured +[Markdown](https://daringfireball.net/projects/markdown). GitHub has a +helpful page on [getting started with writing and formatting Markdown on +GitHub](https://help.github.com/articles/getting-started-with-writing-and-formatting-on-github). + +### Contributing with Pull Requests Reviews {#reviews} + +A big challenge of software development is merging code accurately +without having to wait too much time. For this reason, Reviewers for PRs +are more than welcome! It is a task that requires some experience, but +it's very necessary! Read the [related section below](#reviewing) to +start! + +[Issues and Milestones](#issuesmilestones) +------------------------------------------ + +At `physiopy`, we use Issues and Milestones to keep track of and +organise our workflow. **Issues** describe pieces of work that need to +be completed to move the project forwards. We try to keep them as simple +and clear as possible: an issue should describe a unitary, possibly +small piece of work (unless it's about refactoring). Don't be scared of +opening many issues at once, if it makes sense! Just check that what +you're proposing is not listed in a previous issue (open or closed) yet +(we don't like doubles). Issues get labelled. That helps the +contributors to know what they're about. Check the label list to know +what types are there, and use them accordingly! Issues can also be +**assigned**. If you want to work on an assigned issue, ask permission +first! - **Milestones** set the higher level workflow. They sketch +deadlines and important releases. Issues are assigned to these +milestones by the maintainers. If you feel that an issue should be +assigned to a specific milestone but the maintainers have not done so, +discuss it in the issue chat or in Gitter! We might have just missed it, +or we might not (yet) see how it aligns with the overall project +structure/milestone. + +[Labels](#labeltypes) +-------------------------------------- + +The current list of labels are +[here](https://github.com/physiopy/phys2bids/labels). They can be used +for **Issues**, **PRs**, or both. We use +[auto](https://github.com/intuit/auto) to automate our semantic +versioning and Pypi upload, so **it\'s extremely important to use the +right PR labels**! + +### [Issue & PR labels](#issueprlabels) + +- Documentation: Improvements or additions to documentation. This + category includes (but is not limited to) docs pages, docstrings, + and code comments. +- Duplicate: Whatever this is, it exists already! Maybe it's a closed + Issue/PR, that should be reopened. +- Enhancement: New features added or requested. This normally goes + with a `minormod` label for PRs. +- Outreach: As part of the scientific community, we care about + outreach. Check the relevant section about it, but know that this + Issue/PR contains information or tasks about abstracts, talks, + demonstrations, papers. +- Paused: Issue or PR should not be worked on until the resolution of + other issues or PRs. +- Testing: This is for testing features, writing tests or producing + testing code. Both user testing and CI testing! +- Urgent: If you don\'t know where to start, start here! This is + probably related to a milestone due soon! + +### [Issue-only labels](#issuelabel) + +- Bug: Something isn't working. It either breaks the code or has an + unexpected outcome. +- Community: This issue contains information about the `physiopy` + community (e.g. the next developer call) +- Discussion: Discussion of a concept or implementation. These Issues + are prone to be open ad infinitum. Jump in the conversation if you + want! +- Good first issue: Good for newcomers. These issues calls for a + **fairly** easy enhancement, or for a change that helps/requires + getting to know the code better. They have educational value, and + for this reason, unless urgent, experts in the topic should refrain + from closing them - but help newcomers closing them. +- Hacktoberfest: Dedicated to the hacktoberfest event, so that people + can help and feel good about it (and show it with a T-shirt!). + **Such commits will not be recognised in the all-contributor table, + unless otherwise specified**. +- Help wanted: Extra attention is needed here! It's a good place to + have a look! +- Refactoring: Improve nonfunctional attributes. Which means rewriting + the code or the documentation to improve performance or just because + there's a better way to express those lines. It might create a + `majormod` PR. +- Question: Further information is requested, from users to + developers. Try to respond to this! +- Wontfix: This will not be worked on, until further notice. + +### [PR-only labels](#prlabel) + +#### Labels for semantic release and changelogs + +- Majormod: These PRs call for a new major release (+1.0.0). This + means that the PR is breaking backward compatibility. +- Minormod: These PRs call for a new minor release (0.+1.0). This + means that the PR is **not** breaking backward compatibility. +- BugFIX: These PRs close an issue labelled `bug`. They also increase + the semantic versioning for fixes (+0.0.1). +- Internal: This PR contains changes to the internal API. It won\'t + trigger a release, but it will be reported in the changelog. +- Documentation: See above. This PR won\'t trigger a release, but it + will be reported in the changelog. +- Testing: See above. This PR won\'t trigger a release, but it will be + reported in the changelog. +- Skip release: This PR will **not** trigger a release. +- Release: This PR will force the trigger of a release. + +#### Other labels + +- Invalid: These PRs don\'t seem right. They actually seem so not + right that they won't be further processed. This label invalidates a + Hacktoberfest contribution. If you think this is wrong, start a + discussion in the relevant issue (or open one if missing). Reviewers + are asked to give an explanation for the use of this label. + +### [Good First Issues](#g1i) + +Good First Issues are issues that are either very simple, or that help +the contributor get to know the programs or the languages better. We use +it to help contributors with less experience to learn and familiarise +with Git, GitHub, Python3, and physiology. We invite more expert +contributors to avoid those issues, leave them to beginners and possibly +help them out in the resolution of the issue. However, if the issue is +left unassigned or unattended for long, and it's considered important or +urgent, anyone can tackle it. + +[Contribution workflow](#workflow) +-------------------------------------- + +There are many descriptions of a good contribution workflow out there. +For instance, we suggest to have a look at [tedana's workflow](https://github.com/ME-ICA/tedana/blob/master/CONTRIBUTING.md#making-a-change). +At `physiopy`, we follow a very similar workflow. The only three +differences are: + +- If you see an open issue that you would like to work on, check if it + is assigned. If it is, ask the assignee if they need help or want to + be substituted before starting to work on it. +- We ask you to test the code locally before merging it, and then, if + possible, write some automatic tests for the code to be run in our + Continuous Integration! Check the testing section below to know + more. +- We suggest opening a draft PR as soon as you can - so it's easier + for us to help you! + +[Pull Requests](#pr) +-------------------------------------- + +To improve understanding pull requests \"at a glance\" and use the power +of `auto`, we use the labels listed above. Multiple labels can be +assigned to a PR - in fact, all those that you think are relevant. We +strongly advise to keep the changes you\'re introducing with your PR +limited to your original goal. Adding to the scope of your PR little +style corrections or code refactoring here and there in the code that +you\'re already modifying is a great help, but when they become too much +(and they are not relevant to your PR) they risk complicating the nature +of the PR and the reviewing process. It is much better to open another +PR with the objective of doing such corrections! Moreover, if you\'re +tempted to assign more than one label that would trigger a release (e.g. +bug and minormod or bug and majormod, etc.), you might want to split your PR +instead. When opening a pull request, assign it at least one label. + +We encourage you to open a PR as soon as possible - even before you +finish working on them. This is useful especially to you - so that you +can receive comments and suggestions early on, rather than having to +process a lot of comments in the final review step! However, if it's an +incomplete PR, please open a **Draft PR**. That helps us process PRs by +knowing which one to have a look first - and how picky to be when doing +so. + +Reviewing PRs is a time consuming task and it can be stressful for both +the reviewer and the author. Avoiding wasting time and the need of +little fixes - such as fixing grammar mistakes and typos, styling code, +or adopting conventions - is a good start for a successful (and quick) +review. Before graduating a Draft PR to a PR ready for review, please +check that: + +- You did all you wanted to include in your PR. If at a later stage + you realize something is missing and it's not a minor thing, you + will need to open a new PR. +- If your contribution contains code or tests, you ran and passed all + of the tests locally with [pytest](#testing). +- If you're writing documentation, you built it locally with + sphinx and the format is what you intended. +- Your code is harmonious with the rest of the code - no repetitions + of any sort! +- + +Your code respects the [adopted Style](#styling), especially: + + - Your code is lintered adequately and respects the + [PEP8](https://www.python.org/dev/peps/pep-0008/) + convention. + - Your docstrings follow the + [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) + convention. + - There are no typos or grammatical mistakes and the text is + fluid. + - The code is sufficiently commented and the comments are + clear. + - Your PR title is clear enough to be meaningful when appended + to the version changelog. + +- You have the correct labels. + +To be merged, PRs have to: + +1. Pass all the CircleCI tests, and possibly all the codecov checks. +2. Have the necessary amount of approving reviews, even if you're a + long time contributor. You can ask one (or more) contributor to do + that review, if you think they align more with the content of your + PR. You need **one** review for documentation, tests, and small + changes, and **two** reviews for bugs, refactoring and enhancements. +3. Have at least a release-related label (or a `Skip + release` label). +4. Have a short title that clearly explains in one sentence the aim of + the PR. +5. Contain at least a unit test for your contribution, if the PR + contains code (it would be better if it contains an integration or + function test and all the breaking tests necessary). If you're not + confident about writing tests, it is possible to refer to an issue + that asks for the test to be written, or another (Draft) PR that + contains the tests required. + +As we're trying to maintain at least 90% code coverage, you're strongly +encouraged to write all of the tests necessary to keep coverage above +that threshold. If coverage drops too low, you might be asked to add +more tests and/or your PR might be rejected. See the [Automatic testing](#testing) section. + +Don't merge your own pull request! That\'s a task for the main reviewer +of your PR or the project manager. Remember that the project manager +doesn't have to be a reviewer of your PR! + +[Reviewing PRs](#reviewing) +------------- + +Reviewing PRs is an extremely important task in collaborative +development. In fact, it is probably the task that requires the most +time in the development, and it can be stressful for both the reviewer +and the author. Remember that, as a PR Reviewer, you are guaranteeing +that the changes work and integrate well with the rest of the +repository, hence **you are responsible for the quality of the +repository and its next version release**. If they don\'t integrate +well, later PR reviewers might have to ask for broader changes than +expected. There are many best practices to review code online, for +instance [this one](https://medium.com/an-idea/the-code-review-guide-9e793edcd683), but +here are some good rules of thumbs that we need to follow while +reviewing PRs: + +- Be respectful to the PR authors and be clear in what you are + asking/suggesting - remember that, like you, they are contributing + their spare time and doing their best job! +- If there is a Draft PR, you can comment on its development in the + message board or making "Comment" reviews. Don't ask for changes, + and especially, **don't approve the PR** +- If the PR graduated from Draft to full PR, check that it follows the + sections [Pull requests](#pr) and [Style Guide](#styling) of these + guidelines. If not, invite the author to do so before starting a + review. +- **Don't limit your review to the parts that are changed**. Look at + the entire file, see if the changes fit well in it, and see if the + changes are properly addressed everywhere in the code - in the + documentation, in the tests, and in other functions. Sometimes the + differences reported don't show the full impact of the PR in the + repository! +- If your want to make Pull Requests an educational process, invite + the author of the PR to make changes before actually doing them + yourself. Request changes via comments or in the message board or by + checking out the PR locally, making changes and then submitting a PR + to the author's branch. +- If you decide to use the suggestion tool in reviews, or to start a + PR to the branch under review, please alert the Project Manager. + Bots might automatically assign you contribution types that will + have to be removed (remember, your contribution in this case is + "Reviewer"). Instead of starting a PR to the branch under review, + think about opening a new PR with those modifications (unless they + are needed to pass tests), and alert the Main Reviewer. In any case + **don't commit directly to the branch under review**! +- If you're reviewing documentation, build it locally with `sphinx`. +- If you're asking for changes, **don't approve the PR**. Approve it + only after everything was sufficiently addressed. Someone else might + merge the PR in taking your word for granted. +- If you are the main reviewer, and the last reviewer required to + approve the PR, merge the PR! + +Before approving and/or merging PRs, be sure that: + +- All the tests in CircleCI/Azure pass without errors. +- Prefereably, codecov checks pass as well. If they don\'t, discuss + what to do. +- The title describes the content of the PR clearly enough to be + meaningful on its own - remember that it will appear in the version + changelog! +- The PR has the appropriate labels to trigger the appropriate version + release and update the contributors table. + +### [Main reviewer](#mainreviewer) + +At `physiopy` we use the *Assignees* section of a PR to mark the +**main reviewer** for that PR. The main reviewer is the primary person +responsible **for the quality of the repository and its next version release**, + as well as **for the behaviour of the other reviewers**. The main reviewer takes care of the reviewing process of the PR, in particular: + +- Invites the reviewers to finish their review in a relatively + short time. + +- Checks that all elements of this document were respected, + especially the part about [Pull Requests](#pr). + +- Invites other Reviewers to respect this document, especially + the part about [reviews](#reviewing), helps them in doing + so, and checks that they do. + +- If a Reviewer keeps not respecting this document, flags them + to the project manager. + +- Decides what to do in case of a coverage decrease (in + *codecov/patch*). + +***In case of missing tests or updates to user documentation:*** + +- Asks for more documentation or tests before approving the + PR, *or* + +- Checks that the appropriate issues have been opened to + address the lack of documentation or tests (1 issue per item), *or* + +- Double-checks that the title is clear and the labels are correct to + trigger an appropriate `auto` release - feel free to change them. + +- Main reviewer **Is the one that is going to merge the PR.** + +- **After the PR has been merged and a new release has been triggered, checks that:** + + - The documentation was updated correctly (if changed). + - The Pypi version of the repository coincides with the new + release (if changed). + - New contributors or forms of contributions were correctly + added in the README (if changed). + +Style Guide {#styling} +----------- + +Docstrings should follow +[numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) +convention. We encourage extensive documentation. The python code itself +should follow [PEP8](https://www.python.org/dev/peps/pep-0008/) +convention whenever possible: there are continuous integration tests +checking that! You can use linters to help you write your code following +style conventions. Linters are add-ons that you can run on the written +script file. We suggest the use of **flake8** for Python 3. Many editors +(Atom, VScode, Sublimetext, \...) support addons for online lintering, +which means you'll see warnings and errors while you write the code - +check out if your does! + +Since we adopt [auto](https://intuit.github.io/auto/home.html), the PR +title will be automatically reported as part of the changelog when +updating versions. Try to describe in one (short) sentence what your PR +is about - possibly using the imperative and starting with a capital +letter. For instance, a good PR title could be: +`Implement support for files` or +`Reorder dictionary entries`, rather than ` support` or +`reorders keys`. + +Automatic Testing {#testing} +----------------- + +`physiopy` uses Continuous Integration (CI) to make life easier. In +particular, we use the [CircleCI](https://circleci.com/) platform to run +automatic testing! **Automatic tests** are cold, robotic, emotionless, +and opinionless tests that check that the program is doing what it is +expected to. They are written by the developers and run (by CircleCI) +every time they send a Pull Request to `physiopy` repositories. They +complement the warm, human, emotional and opinionated **user tests**, as +they tell us if a piece of code is failing. CircleCI uses +[pytest](https://docs.pytest.org/en/latest/) to run the tests. The great +thing about it is that you can run it in advance on your local version +of the code! We can measure the amount of code that is tested with +[codecov](https://docs.pytest.org/en/latest/), which is an indication of +how reliable our packages are! We try to maintain a 90% code coverage, +and for this reason, PR should contain tests! The four main type of +tests we use are: + +1. Unit tests : + + : Unit tests check that a minimal piece of code is doing what it + should be doing. Normally this means calling a function with + some mock parameters and checking that the output is equal to + the expected output. For example, to test a function that adds + two given numbers together (1 and 3), we would call the function + with those parameters, and check that the output is 4. + +2. Breaking tests + + : Breaking tests are what you expect - they check that the program + is breaking when it should. This means calling a function with + parameters that are expected **not** to work, and check that it + raises a proper error or warning. + +3. Integration tests + + : Integration tests check that the code has an expected output, + being blind to its content. This means that if the program + should output a new file, the file exists - even if it's empty. + This type of tests are normally run on real data and call the + program itself. For instance, documentation PRs should check + that the documentation page is produced! + +4. Functional tests + + : If integration tests and unit tests could have babies, those + would be functional tests. In practice, this kind of tests check + that an output is produced, and *also* that it contains what it + should contain. If a function should output a new file or an + object, this test passes only if the file exists *and* it is + like we expect it to be. They are run on real or mock data, and + call the program itself or a function. + +Recognising contributors {#recognising} +------------------------ + +We welcome and recognize [all +contributions](https://allcontributors.org/docs/en/specification) from +documentation to testing to code development. You can see a list of +current contributors in the README (kept up to date by the [all +contributors bot](https://allcontributors.org/docs/en/bot/overview)). + +**Thank you!** + +*--- Based on contributing guidelines from the [STEMMRoleModels](https://github.com/KirstieJane/STEMMRoleModels) project.* From 302d4a2bf617a6f9f396dacd2dd9305f3025846a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Lespinasse?= Date: Fri, 13 Nov 2020 13:10:53 -0500 Subject: [PATCH 02/11] minor typos, fix links --- docs/community/CODE_OF_CONDUCT.md | 2 +- docs/community/CONTRIBUTING.md | 2 +- docs/community/contributorfile.md | 14 +++++++------- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/community/CODE_OF_CONDUCT.md b/docs/community/CODE_OF_CONDUCT.md index ffc0ef4..9246239 100644 --- a/docs/community/CODE_OF_CONDUCT.md +++ b/docs/community/CODE_OF_CONDUCT.md @@ -1,4 +1,4 @@ -Physiopy Code of Conduct {#conduct} +[Physiopy Code of Conduct](#conduct) ======================== *Based on the* *Contributor Covenant Code of Conduct*\_. diff --git a/docs/community/CONTRIBUTING.md b/docs/community/CONTRIBUTING.md index 9f83954..1a9904a 100644 --- a/docs/community/CONTRIBUTING.md +++ b/docs/community/CONTRIBUTING.md @@ -1,4 +1,4 @@ -Contributing to `physiopy` {#contributing} +[Contributing to `physiopy`](#contributing) ========================== First of all: thank you! diff --git a/docs/community/contributorfile.md b/docs/community/contributorfile.md index 10e5d55..6c0b1e8 100644 --- a/docs/community/contributorfile.md +++ b/docs/community/contributorfile.md @@ -1,4 +1,4 @@ -How to contribute to `physiopy` {#contributorfile} +[How to contribute to `physiopy`](#contributorfile) =============================== Welcome to the `physiopy` organisation! It's great news that you're @@ -73,7 +73,7 @@ conduct](conduct.html). [Contributions](#contributiontypes) -------------------------------------- -### Contributing with small documentation changes {#smalldocs} +### [Contributing with small documentation changes](#smalldocs) If you are new to GitHub and just have a small documentation change recommendation (such as: typos detection, small improvements in the @@ -82,7 +82,7 @@ it with the "Documentation" label. Chances are those types of changes are easily doable with GitHub\'s online editor, which means you can do them, or ask for help from the developers! -### Contributing with User testing {#usertests} +### [Contributing with User testing](#usertests) Another, non-coding friendly way to contribute to `physiopy` is by testing the packages. There are different kinds of tests, but to @@ -97,7 +97,7 @@ open an issue on GitHub or drop a comment in Gitter, refer to this [blueprint](https://docs.google.com/document/d/1b6wc7JVDs3vi-2IqGg_Ed_oWKbZ6siboAJHf55nodKo/edit?usp=sharing) and don't be afraid to ask questions! -### Contributing with test files {#testfile} +### [Contributing with test files](#testfile) At `physiopy` we always try to imagine and support every possible setting out there. However, our imagination has a limit - but if you @@ -118,13 +118,13 @@ add the file in our [OSF](https://osf.io/3txqr/) space. We're extremely grateful for this type of contribution - so grateful that we asked allcontributors to add a dedicated category! -### Contributing documentation through GitHub {#documenting} +### [Contributing documentation through GitHub](#documenting) We use [readthedocs](https://readthedocs.org/) to create our documentation. Every contribution is welcome and it follows the same steps as a code contribution, explained below. -### Contributing code through GitHub {#code} +### [Contributing code through GitHub](#code) This section covers 90% of the contributions a project like `physiopy` receives - code, documentation and tests. The best way to make this kind @@ -138,7 +138,7 @@ They are based upon GitHub-flavoured helpful page on [getting started with writing and formatting Markdown on GitHub](https://help.github.com/articles/getting-started-with-writing-and-formatting-on-github). -### Contributing with Pull Requests Reviews {#reviews} +### [Contributing with Pull Requests Reviews](#reviews) A big challenge of software development is merging code accurately without having to wait too much time. For this reason, Reviewers for PRs From 51acde481dce599fe563990f490bbfe391c07d9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Lespinasse?= Date: Fri, 13 Nov 2020 13:56:34 -0500 Subject: [PATCH 03/11] rel path --- docs/community/contributorfile.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/community/contributorfile.md b/docs/community/contributorfile.md index 6c0b1e8..fc77b6c 100644 --- a/docs/community/contributorfile.md +++ b/docs/community/contributorfile.md @@ -39,7 +39,7 @@ in this guide? Jump to the following sections: - [Automatic Testing](#testing) - [Recognizing contributors](#recognising) -[Aims of `physiopy`](#aims) +Aims of `physiopy`(#aims) `physiopy` is a **very** young project developed by a bunch of @@ -327,17 +327,17 @@ check that: Your code respects the [adopted Style](#styling), especially: - - Your code is lintered adequately and respects the +- Your code is lintered adequately and respects the [PEP8](https://www.python.org/dev/peps/pep-0008/) convention. - - Your docstrings follow the +- Your docstrings follow the [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) convention. - - There are no typos or grammatical mistakes and the text is +- There are no typos or grammatical mistakes and the text is fluid. - - The code is sufficiently commented and the comments are +- The code is sufficiently commented and the comments are clear. - - Your PR title is clear enough to be meaningful when appended +- Your PR title is clear enough to be meaningful when appended to the version changelog. - You have the correct labels. From a87125fd55dfe307a3c202f2188b6bd3c05b6699 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Lespinasse?= Date: Fri, 13 Nov 2020 14:15:21 -0500 Subject: [PATCH 04/11] reviewing style, linting --- docs/community/contributorfile.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/community/contributorfile.md b/docs/community/contributorfile.md index fc77b6c..89f82a2 100644 --- a/docs/community/contributorfile.md +++ b/docs/community/contributorfile.md @@ -39,8 +39,8 @@ in this guide? Jump to the following sections: - [Automatic Testing](#testing) - [Recognizing contributors](#recognising) -Aims of `physiopy`(#aims) - +[Aims of physiopy](#aims) +============================ `physiopy` is a **very** young project developed by a bunch of researchers from the two different sides of the Atlantic Ocean (for @@ -247,7 +247,7 @@ right PR labels**! #### Other labels -- Invalid: These PRs don\'t seem right. They actually seem so not +- Invalid: These PRs don't seem right. They actually seem so not right that they won't be further processed. This label invalidates a Hacktoberfest contribution. If you think this is wrong, start a discussion in the relevant issue (or open one if missing). Reviewers @@ -323,7 +323,6 @@ check that: sphinx and the format is what you intended. - Your code is harmonious with the rest of the code - no repetitions of any sort! -- Your code respects the [adopted Style](#styling), especially: @@ -342,7 +341,7 @@ Your code respects the [adopted Style](#styling), especially: - You have the correct labels. -To be merged, PRs have to: +#### To be merged, PRs have to: 1. Pass all the CircleCI tests, and possibly all the codecov checks. 2. Have the necessary amount of approving reviews, even if you're a @@ -438,7 +437,9 @@ Before approving and/or merging PRs, be sure that: At `physiopy` we use the *Assignees* section of a PR to mark the **main reviewer** for that PR. The main reviewer is the primary person responsible **for the quality of the repository and its next version release**, - as well as **for the behaviour of the other reviewers**. The main reviewer takes care of the reviewing process of the PR, in particular: + as well as **for the behaviour of the other reviewers**. + +***The main reviewer takes care of the reviewing process of the PR, in particular:*** - Invites the reviewers to finish their review in a relatively short time. @@ -469,7 +470,8 @@ responsible **for the quality of the repository and its next version release**, - Main reviewer **Is the one that is going to merge the PR.** -- **After the PR has been merged and a new release has been triggered, checks that:** + +***After the PR has been merged and a new release has been triggered, checks that:*** - The documentation was updated correctly (if changed). - The Pypi version of the repository coincides with the new @@ -477,8 +479,8 @@ responsible **for the quality of the repository and its next version release**, - New contributors or forms of contributions were correctly added in the README (if changed). -Style Guide {#styling} ------------ +[Style Guide](#styling) +------------------------- Docstrings should follow [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) @@ -501,7 +503,7 @@ letter. For instance, a good PR title could be: `Reorder dictionary entries`, rather than ` support` or `reorders keys`. -Automatic Testing {#testing} +[Automatic Testing](#testing) ----------------- `physiopy` uses Continuous Integration (CI) to make life easier. In @@ -555,7 +557,7 @@ tests we use are: like we expect it to be. They are run on real or mock data, and call the program itself or a function. -Recognising contributors {#recognising} +[Recognising contributors](#recognising) ------------------------ We welcome and recognize [all From aef1cf324ddd2a6bd6a027644a5e0f973f8b46c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Lespinasse?= Date: Fri, 13 Nov 2020 15:08:29 -0500 Subject: [PATCH 05/11] Contributor file minor fixes --- docs/community/contributorfile.md | 61 ++++++++++++++++--------------- mkdocs.yml | 2 +- 2 files changed, 32 insertions(+), 31 deletions(-) diff --git a/docs/community/contributorfile.md b/docs/community/contributorfile.md index 89f82a2..edbea37 100644 --- a/docs/community/contributorfile.md +++ b/docs/community/contributorfile.md @@ -282,6 +282,8 @@ differences are: - We suggest opening a draft PR as soon as you can - so it's easier for us to help you! +See our [complete documentation](CONTRIBUTING.md#contributing) on the matter + [Pull Requests](#pr) -------------------------------------- @@ -324,20 +326,15 @@ check that: - Your code is harmonious with the rest of the code - no repetitions of any sort! -Your code respects the [adopted Style](#styling), especially: - -- Your code is lintered adequately and respects the - [PEP8](https://www.python.org/dev/peps/pep-0008/) - convention. -- Your docstrings follow the - [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) - convention. -- There are no typos or grammatical mistakes and the text is - fluid. -- The code is sufficiently commented and the comments are - clear. -- Your PR title is clear enough to be meaningful when appended - to the version changelog. +Your code respects the [adopted Style](#styling), especially if: + +- Your code is lintered adequately and respects the [PEP8](https://www.python.org/dev/peps/pep-0008/) convention. +- Your docstrings follow the [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) convention. +- There are no typos or grammatical mistakes and the text is fluid. + +- The code is sufficiently commented and the comments are clear. + +- Your PR title is clear enough to be meaningful when appended to the version changelog. - You have the correct labels. @@ -345,7 +342,9 @@ Your code respects the [adopted Style](#styling), especially: 1. Pass all the CircleCI tests, and possibly all the codecov checks. 2. Have the necessary amount of approving reviews, even if you're a - long time contributor. You can ask one (or more) contributor to do + long time contributor. + + Note : You can ask one (or more) contributor to do that review, if you think they align more with the content of your PR. You need **one** review for documentation, tests, and small changes, and **two** reviews for bugs, refactoring and enhancements. @@ -380,18 +379,22 @@ that the changes work and integrate well with the rest of the repository, hence **you are responsible for the quality of the repository and its next version release**. If they don\'t integrate well, later PR reviewers might have to ask for broader changes than -expected. There are many best practices to review code online, for -instance [this one](https://medium.com/an-idea/the-code-review-guide-9e793edcd683), but +expected. + +There are many best practices to review code online, for +instance [this medium blog post](https://medium.com/an-idea/the-code-review-guide-9e793edcd683), but here are some good rules of thumbs that we need to follow while reviewing PRs: -- Be respectful to the PR authors and be clear in what you are +- Be **respectful** to the PR authors and be clear in what you are asking/suggesting - remember that, like you, they are contributing their spare time and doing their best job! -- If there is a Draft PR, you can comment on its development in the + +- If there is a *Draft PR*, you can comment on its development in the message board or making "Comment" reviews. Don't ask for changes, and especially, **don't approve the PR** -- If the PR graduated from Draft to full PR, check that it follows the + +- If the PR graduated *from Draft to full PR*, check that it follows the sections [Pull requests](#pr) and [Style Guide](#styling) of these guidelines. If not, invite the author to do so before starting a review. @@ -414,7 +417,7 @@ reviewing PRs: think about opening a new PR with those modifications (unless they are needed to pass tests), and alert the Main Reviewer. In any case **don't commit directly to the branch under review**! -- If you're reviewing documentation, build it locally with `sphinx`. +- If you're reviewing documentation, build it locally with [`sphinx-build`](https://www.sphinx-doc.org/en/master/man/sphinx-build.html) command. - If you're asking for changes, **don't approve the PR**. Approve it only after everything was sufficiently addressed. Someone else might merge the PR in taking your word for granted. @@ -473,11 +476,9 @@ responsible **for the quality of the repository and its next version release**, ***After the PR has been merged and a new release has been triggered, checks that:*** - - The documentation was updated correctly (if changed). - - The Pypi version of the repository coincides with the new - release (if changed). - - New contributors or forms of contributions were correctly - added in the README (if changed). +- The documentation was updated correctly (if changed). +- The Pypi version of the repository coincides with the new release (if changed). +- New contributors or forms of contributions were correctly added in the README (if changed). [Style Guide](#styling) ------------------------- @@ -524,7 +525,7 @@ tests we use are: 1. Unit tests : - : Unit tests check that a minimal piece of code is doing what it + Unit tests check that a minimal piece of code is doing what it should be doing. Normally this means calling a function with some mock parameters and checking that the output is equal to the expected output. For example, to test a function that adds @@ -533,14 +534,14 @@ tests we use are: 2. Breaking tests - : Breaking tests are what you expect - they check that the program + Breaking tests are what you expect - they check that the program is breaking when it should. This means calling a function with parameters that are expected **not** to work, and check that it raises a proper error or warning. 3. Integration tests - : Integration tests check that the code has an expected output, + Integration tests check that the code has an expected output, being blind to its content. This means that if the program should output a new file, the file exists - even if it's empty. This type of tests are normally run on real data and call the @@ -549,7 +550,7 @@ tests we use are: 4. Functional tests - : If integration tests and unit tests could have babies, those + If integration tests and unit tests could have babies, those would be functional tests. In practice, this kind of tests check that an output is produced, and *also* that it contains what it should contain. If a function should output a new file or an diff --git a/mkdocs.yml b/mkdocs.yml index d0423ce..58b709e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -32,7 +32,7 @@ markdown_extensions: - codehilite - footnotes - toc: - permalink: true + permalink: "#" - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg From 097d3de39742dc772fb554de36a9eb4e247d19dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Lespinasse?= Date: Fri, 13 Nov 2020 15:19:23 -0500 Subject: [PATCH 06/11] including best practices in docs/community --- docs/community/best-practices.md | 260 +++++++++++++++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 docs/community/best-practices.md diff --git a/docs/community/best-practices.md b/docs/community/best-practices.md new file mode 100644 index 0000000..4490882 --- /dev/null +++ b/docs/community/best-practices.md @@ -0,0 +1,260 @@ +[Best Practices for Collecting Physiological Data](#bestpractice) +================================================ + +This document provides a succinct introduction to what physiological +data are typically recorded during an fMRI experiment, how these signals +are recorded, and how these signals can improve our modeling of fMRI +time series data. This is an active field of research, and we encourage +all users to get the latest recommendations prior to initiating a new +study. For a more in-depth article on similar subject matter, please see +[Bulte and Wartolowska (2017) Neuroimage +154:81-91](https://www.sciencedirect.com/science/article/pii/S1053811916306929). + +[Why collect physiological data?](#whycollectphysdata) +------------------------------- + +Physiological monitoring is a key component of understanding +physiological sources of signal variance in fMRI data. Monitoring +physiology during scanning is critical to enable the characterization of +a given subject\'s physiologic state at the time of the scan, and to +track variations in physiology throughout the scan. With these data, we +can more accurately model how these factors manifest in the fMRI signal +time series. + +Physiological fluctuations can be identified as \"noise\" or as +\"signals of interest\", depending on the research question of the +imaging experiment. For most fMRI experiments, the goal is to isolate +signal fluctuations that are associated with a neural stimulus and the +resulting hemodynamic response (Caballero-Gaudes et al. 2016). In these +data, it is important to model and remove signals with a non-neural +origin, such as breathing or cardiac related signal variance. Removing +these confounds will improve the sensitivity and confidence of the fMRI +analysis. In some fMRI experiments, the goal is to characterize a +physiologic effect (for example, studies that map cerebrovascular +reactivity aim to quantify the dilation of blood vessels during certain +non-neural stimuli) (Caballero-Gaudes et al. 2016). In these studies it +is essential that the relevant physiologic parameters are recorded so +that the analysis produces robust, quantitative physiological parameter +maps. + +Another benefit of collecting physiological data is that it provides a +method to monitor the subject and/or patient during the scan in +real-time. Any sudden changes in the different aspects being monitored +can help those in the control room identify if the person is under +duress or complying with the scan protocol. Looking out for these +changes is particularly helpful during an individual\'s first MRI scan, +when they may react poorly to the scan environment. In some protocols, +tracking physiology in real-time can ensure that values stay within +safe, IRB-approved limits. + +Although current modeling of physiology is imperfect, and fMRI signal +processing techniques do not yet accurately factor in all physiologic +signals, the field continues to develop and our modeling continues to +improve. We encourage all fMRI researchers to collect these data to more +fully capture the variable human physiology inherent to imaging +experiments. + +[How are typical physiological data collected?](#differenttypesofphysdata) +--------------------------------------------- + +The most common types of physiological data acquired in fMRI analysis +are cardiac pulsation (pulse), breathing (chest position), and expired +gas concentrations (particularly CO2 and O2). + +**Cardiac pulsation** can be collected via a sensor on the fingertip (or +ear lobe, toe, or other pulse point). These devices are often known as a +photoplethysmograph, and typically are included in the MRI scanner +infrastructure. The data can thus be collected by the scanner, or +recorded by a separate device. Typically the peaks of the cardiac +pulsation trace are identified (e.g., the timing of each heart beat). +Cardiac pulsation causes local movement artifacts, particularly around +large arterial vessels, the edges of the ventricles, and in brainstem +areas (Dagli et al. 1999). RETROICOR (Glover et al. 2000) is one cardiac +denoising example, where the timing of each fMRI acquisition relative to +the nearest cardiac peak is used to model and remove these local +pulsation artifacts. Low frequency changes in heart rate have also been +modeled and shown to influence the fMRI time series (Shmueli et al. +2007, Chang et al. 2009). + +**Breathing** is typically monitored using a \"respiratory belt\" around +the participant\'s chest/diaphragm. The belt may be rigid or elastic, +using MR compatible force or pressure transducers to generate a signal +proportional to the chest diameter. The optimal positioning of the belt +depends on the device being used, however it is best to be fairly +consistent in how the belt is worn throughout a study. In some labs, +multiple belts are used to better capture different types of breathing +styles (e.g., \"chest breathing\" versus \"belly breathing\"). Often a +belt is incorporated into the MRI scanner infrastructure, and these data +can be collected by the scanner or recorded by a separate device. The +peaks and troughs of the breathing trace are identified, which can +provide information about breathing rate as well as breathing depth. +There are three primary ways by which breathing can influence the fMRI +signals. First, breathing often leads to bulk motion of the body and +head (Brosch et al. 2002). These effects are typically modeled using +volume registration and motion correction algorithms. Second, breathing +changes the chest position which can influence the success of the shim, +continuously changing B0 homogeneity throughout the scan and in turn +affecting signal amplitude (Brosch et al. 2002, Raj et al. 2001). These +effects are also modeled using techniques like RETROICOR. Thirdly, +changing breathing rate and depth can influence blood gases, which can +drive vasodilation or vasoconstriction, and thus substantially influence +the fMRI signal amplitude (Chang and Glover 2009). RVT correction (Birn +et al. 2008) estimates the change in breathing rate/depth to model these +effects. + +**Blood gases** It is also possible (and recommended!) to directly +record changes in blood gas levels, rather than infer them from a chest +position measurement. Most commonly we measure carbon dioxide levels +(CO2), which is a known vasodilator and can drive large variability in +blood flow and the BOLD signal (Birn et al. 2006, Wise et al. 2004). We +can also measure oxygen (O2) levels; O2 only has a mild vasoconstrictive +effect on the cerebrovasculature, but O2 levels can directly influence +BOLD signal contrast (Bulte et al. 2007). These two blood gases are +typically strongly anticorrelated with each other in most scans, but can +also be manipulated independently and influence the fMRI signals through +distinct mechanisms (Floyd et al. 2003). Best practice would be to +record both. Although the most accurate recordings of blood gas levels +would be achieved through arterial sampling, this is not recommended for +most imaging experiments. Instead, the concentrations of CO2 and O2 in +arterial blood can be approximated by the partial pressure of each gas +at the end of an exhalation, or the end-tidal partial pressure (commonly +abbreviated as PETCO2 and PETO2) (Bengtsson et al. 2001, McSwain et al. +2010). The person being scanned wears a nasal cannula (soft plastic tube +that rests just below the nostrils) or face mask that is connected to a +gas analyzer in the control room. The resulting data shows the +fluctuations in CO2 and O2 across every breath; an algorithm must +extract the \"end-tidal\" values. + +[What equipment is needed?](#howtocollectphysdata) +------------------------- + +Peripheral devices: + +- finger photoplethysmograph (pulse-oximeter) +- respiratory belt +- disposable nasal cannula (or face mask) +- long sample line to connect from the scan room to the control room + +Some peripheral devices can be passed through a void in the penetration +panel from the control room to the scan room (e.g., gas sampling line); +others must be plugged into the penetration panel for noise filtering +(e.g., some pulse sensors). Devices native to the MRI scanner may +communicate wirelessly with the scanner. When adding non-native +peripheral devices to the scanner environment, we recommend that you +check that you are not bringing any outside noise into the scan room or +bringing too much scanner noise into the physiological recordings. It +may be necessary to develop additional devices or mechanisms to shield +these connections. + +Recording devices: + +- CO2 and O2 analyzer +- analog-to-digital converter (ADC) or other data acquisition (DAQ) + device +- associated signal recording/analysis software + +For example, ADInstruments sells the Powerlab and uses LabChart +software; Biopac sells the MP160 and uses AcqKnowledge software. It is +also important to sync the physiological recordings with the fMRI scan +triggers. To do this, it will be necessary to extract the trigger pulses +from your MRI scanner, typically inputting these analog signals via BNC +into the same ADC that is recording the physiological information. + +[What to do with physiological data once it has been collected?](#whattodowithphysdata) +-------------------------------------------------------------- + +Ideally you have recorded physiological data throughout the entire scan +session, and have trigger data to identify when scanning occurred. +Phys2bids can be used to organize the various physiological data traces +that you have collected. With this program, your data will have the +appropriate BIDS labels to describe physiological information. As a +sanity check, you should quickly plot each trace to ensure that it +matches the type of information you think you collected. + +After this restructuring of the data, there are numerous tools available +to process each type of physiological trace, identifying end-tidal +values for O2 and CO2, and phases of the cardiac and respiratory cycles. +These data are then further processed via smoothing or convolution to +create physiological regressors, which can be incorporated into a +generalized linear model framework to explain portions of your fMRI +signal attributed to physiological effects. + +References +---------- + +Bengtsson, J., Bake, B., Johansson, A., & Bengtson, J. P. (2001). +End-tidal to arterial oxygen tension difference as an oxygenation index. +Acta Anaesthesiologica Scandinavica, 45(3), 357--363. + + +Birn, R. M., Diamond, J. B., Smith, M. A., & Bandettini, P. A. (2006). +Separating respiratory-variation-related fluctuations from +neuronal-activity-related fluctuations in fMRI. NeuroImage, 31(4), +1536--1548. + +Birn, R. M., Smith, M. A., Jones, T. B., & Bandettini, P. A. (2008). The +respiration response function: The temporal dynamics of fMRI signal +fluctuations related to changes in respiration. NeuroImage, 40(2), +644--654. + +Brosch, J. R., Talavage, T. M., Ulmer, J. L., & Nyenhuis, J. A. (2002). +Simulation of human respiration in fMRI with a mechanical model. IEEE +Transactions on Biomedical Engineering, 49(7), 700--707. + + +Bulte, D. P., Chiarelli, P. A., Wise, R. G., & Jezzard, P. (2007). +Cerebral perfusion response to hyperoxia. Journal of Cerebral Blood Flow +and Metabolism : Official Journal of the International Society of +Cerebral Blood Flow and Metabolism, 27(1), 69--75. + + +Bulte, D., & Wartolowska, K. (2017). Monitoring cardiac and respiratory +physiology during FMRI. NeuroImage, 154, 81--91. + + +Caballero-Gaudes, C., & Reynolds, R. C. (2017). Methods for cleaning the +BOLD fMRI signal. NeuroImage, 154(December 2016), 128--149. + + +Chang, C., Cunningham, J. P., & Glover, G. H. (2009). Influence of heart +rate on the BOLD signal: The cardiac response function. NeuroImage, +44(3), 857--869. + +Chang, C., & Glover, G. H. (2009). Relationship between respiration, +end-tidal CO2, and BOLD signals in resting-state fMRI. NeuroImage, +47(4), 1381--1393. + +Dagli, M. S., Ingeholm, J. E., & Haxby, J. V. (1999). Localization of +cardiac-induced signal change in fMRI. NeuroImage, 9(4), 407--415. + + +Floyd, T. F., Clark, J. M., Gelfand, R., Detre, J. A., Ratcliffe, S., +Guvakov, D., ... Eckenhoff, R. G. (2003). Independent cerebral +vasoconstrictive effects of hyperoxia and accompanying arterial +hypocapnia at 1 ATA. Journal of Applied Physiology, 95(6), 2453--2461. + + +Glover, G. H., Li, T., & Ress, D. (2000). Image‐based method for +retrospective correction of physiological motion effects in fMRI: +RETROICOR. Magnetic Resonance in Medicine, 44(1), 162--167. +\<162::AID-MRM23\>3.0.CO;2-E + +McSwain, S. D., Hamel, D. S., Smith, P. B., Gentile, M. A., Srinivasan, +S., Meliones, J. N., & Cheifetz, I. M. (2010). End-tidal and arterial +carbon dioxide measurements correlate across all levels of physiologic +dead space. Respiratory Care, 55(3), 288--293. + +Raj, D., Anderson, A. W., & Gore, J. C. (2001). Respiratory effects in +human functional magnetic resonance imaging due to bulk susceptibility +changes. Phys. Med. Biol, 46, 3340. + +Shmueli, K., van Gelderen, P., de Zwart, J. A., Horovitz, S. G., +Fukunaga, M., Jansma, J. M., & Duyn, J. H. (2007). Low-frequency +fluctuations in the cardiac rate as a source of variance in the +resting-state fMRI BOLD signal. NeuroImage, 38(2), 306--320. + + +Wise, R. G., Ide, K., Poulin, M. J., & Tracey, I. (2004). Resting +fluctuations in arterial carbon dioxide induce significant low frequency +variations in BOLD signal. NeuroImage, 21(4), 1652--1664. + From dacee1f0e4dcd3dc640c7eb7b96698380b19aed7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Lespinasse?= Date: Fri, 13 Nov 2020 15:25:57 -0500 Subject: [PATCH 07/11] dropping CONTRIBUTING which is phys2bids centered --- docs/community/CONTRIBUTING.md | 129 --------------------------------- 1 file changed, 129 deletions(-) delete mode 100644 docs/community/CONTRIBUTING.md diff --git a/docs/community/CONTRIBUTING.md b/docs/community/CONTRIBUTING.md deleted file mode 100644 index 1a9904a..0000000 --- a/docs/community/CONTRIBUTING.md +++ /dev/null @@ -1,129 +0,0 @@ -[Contributing to `physiopy`](#contributing) -========================== - -First of all: thank you! - -Contributions can be made in different ways, not only code! As we follow -the -[all-contributors](https://github.com/all-contributors/all-contributors) -specification, any contribution will be recognised accordingly. - -Follow these steps to get started: - -1. Have a look at the [contributor guide](contributorfile.html) page as - well as the [code of conduct](conduct.html). -2. Make sure that you have a GitHub account. You can set up a [free - GitHub account](https://github.com/); here are some - [instructions](https://help.github.com/articles/signing-up-for-a-new-github-account). -3. If you intend to contribute code and/or use the `physiopy` packages - in any way, check that you have `git` and `pip` installed on your - system. Then install `phys2bids` as a developer. This will let you - run the program with the latest modifications, without requiring to - re-install it every time. - -::: {.note} -::: {.admonition-title} -Note -::: - -The following instructions are provided assuming that python 3 is -**not** your default version of python. If it is, you might need to use -`pip` instead of `pip3`, although some OSs do adopt `pip3` anyway. If -you want to check, type `python --version` in a terminal. -::: - -Linux, Mac, and Windows developer installation ----------------------------------------------- - -Be sure to have `git` and `pip` installed. Fork the phys2bids repository -in GitHub, then open a terminal and run the following code to clone the -forked repository and set it as your \`origin\`: - - git clone https://github.com/{username}/phys2bids.git - # or in case you prefer to use ssh: - git clone git@github.com:{username}/phys2bids.git - -We also recommend to set up the physiopy/phys2bids repository as -`upstream`. In this way you can always keep your main branch -up to date with the command ``git pull upstream master``: - - cd phys2bids - git remote add upstream https://github.com/physiopy/phys2bids.git - git pull upstream master - - -### Basic installation - -If you use python frequently, or you are a python developer, chances are -that all the necessary dependencies are already installed in your -system. - -Move into the `phys2bids` folder and execute the command: - - pip3 install -e . - -### Full developer installation - -If it\'s your first experience as a python developer, or you just want -to be sure that you have everything you need to collaborate with us, you -can install `phys2bids` with all the other packages that we frequently -use during development in one step! - -Move into the `phys2bids` folder and execute the command: - - pip3 install -e .[all] - -This will install: - -> - `phys2bids` as an editable package, which means that you can -> modify the program and run it without having to reinstall it every -> time! -> - All `phys2bids` dependencies. -> - All **interface** modules, that deal with the interfaces for all -> the file formats. -> - All **style** modules, such as `flake8`, to help you linter the -> code! -> - All **documentation** modules, like `sphinx`, so that you can -> build the docs locally before submitting them. -> - All **test** modules, like `pytest`, in order for you to test your -> code locally before committing it! - -### Check your installation! - -Type the commands: - - cd phys2bids/tests - pytest - -This will execute the tests locally and check that your phys2bids -installation works properly. - - pytest - =================================== test session starts =================================== - platform win32 -- Python 3.8.6, pytest-6.1.1, py-1.9.0, pluggy-0.13.1 - rootdir: C:\Users\sento\phys2bids, configfile: setup.cfg - plugins: cov-2.10.1 - collected 61 items - - test_acq.py . [ 1%] - test_bids.py ................ [ 27%] - test_integration.py ... [ 32%] - test_phys2bids.py ... [ 37%] - test_physio_obj.py ....... [ 49%] - test_txt.py .................. [ 78%] - test_utils.py ........... [ 96%] - test_viz.py .x [100%] - - ================================= short test summary info ================================= - XFAIL test_viz.py::test_plot_trigger - ======================== 60 passed, 1 xfailed in 142.58s (0:02:22) ======================== - - -Do **not** worry if there is a xfail error in the log. This happens when -we know that a test will fail for known reasons, and we are probably -working to fix it (see -[here](https://docs.pytest.org/en/latest/skipping.html#xfail-mark-test-functions-as-expected-to-fail). -However, if you do encounter any other error, check that you have all -the extra dependencies installed and their version meets `phys2bids` -requirements. Contact us on -[gitter](https://gitter.im/physiopy/community) if you need help! From 99d87f4286d1773a7eff040b13a76dd48618ef15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Lespinasse?= Date: Tue, 17 Nov 2020 16:10:30 -0500 Subject: [PATCH 08/11] adding contributing file --- docs/community/CODE_OF_CONDUCT.md | 4 +- docs/community/contributing.md | 123 ++++++++++++++++++++++++++++++ 2 files changed, 125 insertions(+), 2 deletions(-) create mode 100644 docs/community/contributing.md diff --git a/docs/community/CODE_OF_CONDUCT.md b/docs/community/CODE_OF_CONDUCT.md index 9246239..b433bb9 100644 --- a/docs/community/CODE_OF_CONDUCT.md +++ b/docs/community/CODE_OF_CONDUCT.md @@ -131,10 +131,10 @@ within the project community. Attribution ----------- -This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.0, available at . Community Impact Guidelines were inspired by Mozilla's code of conduct -enforcement ladder https://github.com/mozilla/diversity. +enforcement ladder . For answers to common questions about this code of conduct, see the FAQ at . Translations are diff --git a/docs/community/contributing.md b/docs/community/contributing.md new file mode 100644 index 0000000..3efee36 --- /dev/null +++ b/docs/community/contributing.md @@ -0,0 +1,123 @@ +[Contributing to `physiopy`](#contributing) +========================== + +First of all: thank you! + +Contributions can be made in different ways, not only code! As we follow +the +[all-contributors](https://github.com/all-contributors/all-contributors) +specification, any contribution will be recognised accordingly. + +Follow these steps to get started: + +1. Have a look at the [contributor guide](contributorfile.html) page as + well as the [code of conduct](conduct.html). +2. Make sure that you have a GitHub account. You can set up a [free + GitHub account](https://github.com/); here are some + [instructions](https://help.github.com/articles/signing-up-for-a-new-github-account). +3. If you intend to contribute code and/or use the `physiopy` packages + in any way, check that you have `git` and `pip` installed on your + system. Then install the package as a developer. This will let you + run the program with the latest modifications, without requiring to + re-install it every time. + +### NOTE : +The following instructions are provided assuming that python 3 is +**not** your default version of python. If it is, you might need to use +`pip` instead of `pip3`, although some OSs do adopt `pip3` anyway. If +you want to check, type `python --version` in a terminal. + + +Linux, Mac, and Windows developer installation +---------------------------------------------- + +Be sure to have `git` and `pip` installed. Fork the phys2bids repository +in GitHub, then open a terminal and run the following code to clone the +forked repository and set it as your \`origin\`: + + git clone https://github.com/{username}/{physiopy-package}.git + # or in case you prefer to use ssh: + git clone git@github.com:{username}/{physiopy-package}.git + +We also recommend to set up the physiopy/{physiopy-package} repository as +*upstream*. In this way you can always keep your main branch +up to date with the command *git pull upstream master*: + + cd {physiopy-package} + git remote add upstream https://github.com/physiopy/{physiopy-package}.git + git pull upstream master + +### Basic installation + +If you use python frequently, or you are a python developer, chances are +that all the necessary dependencies are already installed in your +system. + +Go to a physiopy package directory (e.g. the `phys2bids` folder) and execute the command: + + pip3 install -e . + +### Full developer installation + +If it's your first experience as a python developer, or you just want +to be sure that you have everything you need to collaborate with us, you +can install `phys2bids` with all the other packages that we frequently +use during development in one step! + +Go to a physiopy package directory (e.g. the `phys2bids` folder) and execute the command: + + pip3 install -e .[all] + +This will install: + +> - `phys2bids` as an editable package, which means that you can +> modify the program and run it without having to reinstall it every +> time! +> - All `phys2bids` dependencies. +> - All **interface** modules, that deal with the interfaces for all +> the file formats. +> - All **style** modules, such as `flake8`, to help you linter the +> code! +> - All **documentation** modules, like `sphinx`, so that you can +> build the docs locally before submitting them. +> - All **test** modules, like `pytest`, in order for you to test your +> code locally before committing it! + +### Check your installation! + +Type the commands: + + cd phys2bids/tests + pytest + +This will execute the tests locally and check that your phys2bids +installation works properly. + + pytest + =================================== test session starts =================================== + platform win32 -- Python 3.8.6, pytest-6.1.1, py-1.9.0, pluggy-0.13.1 + rootdir: C:\Users\sento\phys2bids, configfile: setup.cfg + plugins: cov-2.10.1 + collected 61 items + + test_acq.py . [ 1%] + test_bids.py ................ [ 27%] + test_integration.py ... [ 32%] + test_phys2bids.py ... [ 37%] + test_physio_obj.py ....... [ 49%] + test_txt.py .................. [ 78%] + test_utils.py ........... [ 96%] + test_viz.py .x [100%] + + ================================= short test summary info ================================= + XFAIL test_viz.py::test_plot_trigger + ======================== 60 passed, 1 xfailed in 142.58s (0:02:22) ======================== + +Do **not** worry if there is a xfail error in the log. This happens when +we know that a test will fail for known reasons, and we are probably +working to fix it (see +[here](https://docs.pytest.org/en/latest/skipping.html#xfail-mark-test-functions-as-expected-to-fail). +However, if you do encounter any other error, check that you have all +the extra dependencies installed and their version meets `phys2bids` +requirements. Contact us on +[gitter](https://gitter.im/physiopy/community) if you need help! From 97d545a4d019ca83087621de8207c6e1d4463813 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Lespinasse?= Date: Fri, 20 Nov 2020 11:09:03 -0500 Subject: [PATCH 09/11] answering to enekos review --- docs/community/features.md | 0 docs/libraries/peakdet.md | 1 + docs/libraries/singularity.md | 1 - mkdocs.yml | 23 ++++++++++++----------- 4 files changed, 13 insertions(+), 12 deletions(-) delete mode 100644 docs/community/features.md create mode 100644 docs/libraries/peakdet.md delete mode 100644 docs/libraries/singularity.md diff --git a/docs/community/features.md b/docs/community/features.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/libraries/peakdet.md b/docs/libraries/peakdet.md new file mode 100644 index 0000000..2efae18 --- /dev/null +++ b/docs/libraries/peakdet.md @@ -0,0 +1 @@ +# Peakdet diff --git a/docs/libraries/singularity.md b/docs/libraries/singularity.md deleted file mode 100644 index 2339b6b..0000000 --- a/docs/libraries/singularity.md +++ /dev/null @@ -1 +0,0 @@ -## peakdet diff --git a/mkdocs.yml b/mkdocs.yml index 58b709e..3b3ea59 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,20 +8,21 @@ site_url: https://physiopy.github.io copyright: Copyright © 2020 nav: - - Home: index.md + - Home: docs/index.md - Libraries: - - phys2bids: libraries/phys2bids.md - - phys2denoise: libraries/phys2denoise.md - - peakdet: libraries/peakdet.md + - phys2bids: docs/libraries/phys2bids.md + - phys2denoise: docs/libraries/phys2denoise.md + - peakdet: docs/libraries/peakdet.md - Community: - - Welcome: community/index.md - - Membership: community/members.md - - New features: community/features.md - - Contributing: community/CONTRIBUTING.md - - Code of Conduct: community/CODE_OF_CONDUCT.md + - Welcome: docs/community/index.md + - Membership: docs/community/members.md + - Collecting physiological data: docs/community/best-practices.md + - Contributing: docs/community/contributing.md + - Contributor Guide: docs/community/contributorfile.md + - Code of Conduct: docs/community/CODE_OF_CONDUCT.md - Developers: - - Versions Matrix: devs/versions.md - - Releases: devs/releases.md + - Versions Matrix: docs/devs/versions.md + - Releases: docs/devs/releases.md theme: name: material features: From 48a67d50992b47e46a37903de79acdf0cd39b4b7 Mon Sep 17 00:00:00 2001 From: Sangfrois Date: Fri, 27 Nov 2020 12:40:39 -0500 Subject: [PATCH 10/11] links work, build works, added absolute domain path for library --- mkdocs.yml | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 3b3ea59..a36756e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,21 +8,21 @@ site_url: https://physiopy.github.io copyright: Copyright © 2020 nav: - - Home: docs/index.md + - Home: index.md - Libraries: - - phys2bids: docs/libraries/phys2bids.md - - phys2denoise: docs/libraries/phys2denoise.md - - peakdet: docs/libraries/peakdet.md + - phys2bids: 'https://phys2bids.readthedocs.io/en/latest/' + - phys2denoise: libraries/phys2denoise.md + - peakdet: libraries/peakdet.md - Community: - - Welcome: docs/community/index.md - - Membership: docs/community/members.md - - Collecting physiological data: docs/community/best-practices.md - - Contributing: docs/community/contributing.md - - Contributor Guide: docs/community/contributorfile.md - - Code of Conduct: docs/community/CODE_OF_CONDUCT.md + - Welcome: community/index.md + - Membership: community/members.md + - Collecting physiological data: community/best-practices.md + - Contributing: community/contributing.md + - Contributor Guide: community/contributorfile.md + - Code of Conduct: community/CODE_OF_CONDUCT.md - Developers: - - Versions Matrix: docs/devs/versions.md - - Releases: docs/devs/releases.md + - Versions Matrix: devs/versions.md + - Releases: devs/releases.md theme: name: material features: From 1ea426b5c10ee4ccf4139664147aa101dae2065b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eneko=20Uru=C3=B1uela?= <13706448+eurunuela@users.noreply.github.com> Date: Wed, 2 Dec 2020 13:16:16 +0100 Subject: [PATCH 11/11] Update docs/community/contributing.md --- docs/community/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 3efee36..360de6f 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -21,7 +21,7 @@ Follow these steps to get started: run the program with the latest modifications, without requiring to re-install it every time. -### NOTE : +### Note The following instructions are provided assuming that python 3 is **not** your default version of python. If it is, you might need to use `pip` instead of `pip3`, although some OSs do adopt `pip3` anyway. If