Skip to content

Home

Jump to bottom
Martin Shetty edited this page Sep 27, 2020 · 105 revisions

Thank you for taking an interest in contributing to our project.

Please read all of the following before you begin working on something.

Please read at least halfway down before even cloning the repository!

We realize this is a lot of material. Follow the relevant links, but make time to come back and read more when possible.

Join our team

Firstly, you should join us on our Slack channels, where we conduct most of our day-to-day communication. Please mail us at [email protected] to receive an invitation.

Please:

  • include your github username so we can add you to our organization
  • tell us something about your background and area of interest so we can ping the right people to get you up to speed

You should also review our general onboarding guide.

Once you receive an invitation to our Google Suite, please accept it so you have write access to our google drive folders.

Transparency and action

  • Bias towards action. If you think something can be improved, do not ask for permission. Just do it! We can discuss any objections at a later meeting. Git keeps a history of everything, so it is literally impossible to make an irreversible mistake.
  • If you think we are doing something wrong, say it! We are trying to get a lot done and fast, so we should be aware of our mistakes ASAP.
  • If you think you are sitting around with nothing to do and your talent is going to waste, say something. Or just take charge.
  • Try to have fun!

Purpose of wiki

The purpose of this wiki is to define the best practices for collaborating on the repository.

The wiki should contain no technical content, such as requirements, design or engineering decisions, because we want to explicitly track all of this with full version control in the main repository.

Otherwise, please feel free to add any helpful information to this guide.

Purpose of repository

The repository tracks the entirety of the ventilator design - hardware, software, requirements, testing. The goal is to make it possible for someone to build the ventilator based on the information provided in the repository. Until the design is "complete", the repository must represent whatever is the latest state of our prototype design.

Somewhat uniquely, we track a lot of non-software content in the repository, including a lot of "readme's" and other documents that might seem to be better candidates for the wiki. However, tracking this documentation in the repository is better because it ensures:

  • superior version control
  • strict procedures for peer review
  • automated scripts that periodically check the validity of all links

There is no expectation that the information in this repository reflect a final unalterable design. If there is anything potentially helpful to building or testing a prototype or any of its components, please add this information to the repository.

The goal is maximum visibility and and discoverability by all possible collaborators, including ones from outside of our team. If you add any content, link it from somewhere obvious. If there is not one obvious place to link from, link from all potentially related pages. Cross-link as much as needed.

Git and markdown

If you do not have experience in open source software projects, you may not be familiar with git and markdown.

Git is a system for versioning code and documentation, and is particularly powerful for collaborating on complex technical projects in distributed teams.

Markdown is a simple HTML-like language for drafting documentation, such as this page.

If any of this is new to you, please start with our git basics guide.

Cloning (with Large File Storage)

Before you clone the repository to your local machine, you must install git-lfs. We have many large binary files related to CAD and PCB design which are tracked using the Git Large File Storage extension (henceforth LFS). If you do not have LFS installed, those files will not be cloned to your local file system correctly. You will also be unable to commit similar files correctly.

You can install git-lfs with either apt or brew depending on your system.

After this, you can clone the repository as usual and the LFS-tracked files will be downloaded correctly

git clone [email protected]:RespiraWorks/Ventilator.git

For special cases when you do want to clone only the (mostly) text-based parts of the repository, ignoring the LFS content, this can still be done using

GIT_LFS_SKIP_SMUDGE=1 git clone [email protected]:RespiraWorks/Ventilator.git

Already cloned?

If you are new to the project and you jumped the gun and cloned the repo without LFS, you can still correct this. Install git-lfs as above and now in your repo directory run the following to bring in the missing files:

git lfs pull

LFS migration fallout

If you are already a contributor, our recent migration to LFS may have invalidated your local copy. Should you discover yourself unable to pull master, try

 git reset --hard origin

For more details on the LFS migration, check out issue #863.

Adding new binary files

If you are adding any binary (non-text) files to the repository you must use LFS. File types that are by default added to LFS are listed in .gitattributes. Check that all your binary files are covered by this. If you are introducing a new file type that is not already covered, you should first add this filter by running something like:

git lfs track "*.psd"

Precommit hooks

If you intend to check out and edit the repository locally, you should install pre-commit and activate it for this repository. We use pre-commit to autoformat code and for other things.

Install pre-commit (debian/ubuntu):

(sudo) pip install pre-commit

or (macOS):

brew install pre-commit

Then activate pre-commit in this repository.

pre-commit install

Now, every time you commit, this utility will check your changed files for formatting issues. If it reports any problems, it will also fix those files. So all you have to do is add and commit again.

Consequently, if you need to trigger pre-commit to check specific files, just edit those files by adding some whitespace, and make a commit.

If at any point you want to run pre-commit over all the changes in your branch (e.g. to reformat things), try

pre-commit run --from-ref $(git merge-base origin/master HEAD) --to-ref HEAD

If you fail to do this, automatic checks will fail and you will not be allowed to merge your changes.

Code Review

We are creating a life-critical medical device. Rigorous code review is essential for quality assurance. Each pull request (henceforth: PR) must be reviewed by at least one other person. When you create a PR, it is posted automatically to #repo-notifications channel. To find a reviewer, either see who authored or reviewed recent changes to this file, or ask around on Slack.

If a reviewer makes a comment or request for changes, do not close this comment yourself. It is for your reviewer to decide that they are satisfied with your changes and/or explanation of that particular issue.

You can merge only if all CI checks have passed, and after all reviewers have either approved the full contents of the PR or indicated that you don't need to wait for their approval.

After "approval with comments", it's fine to address the comments and merge the PR if the changes are trivial. Beware: some changes are less trivial than they seem, we've had bugs introduced post-approval. When in doubt, ask for another review round.

While documentation is not as fragile as software, it is also harder to error-check in automated ways. Therefore, we require peer review for all changes, not just for code.

For more on how PR's work in github, read this.

Continuous integration

We run continuous integration services for this repository. This includes:

  • proken link checks for all markdown pages
  • builds and unit tests of controller and GUI code
  • publishing of test coverage reports at codecov.io.
  • Integration tests with hardware -- coming soon

Currently, CI jobs are run in circle.ci. Please make sure you can log in and view the test logs. You can authenticate in CircleCi using your github credentials.

When any checks fail for your PR's, there will be direct links to the failing CI jobs from the PR panel.

Occasionally, the dead-link-test will fail for completely valid links in the documentation. This is because some websites quite understandably block crawler bots like our link checker. In such cases, you will need to whitelist that link's domain by modifying the CI script at .circleci/config.yml.

Workflow

We follow trunk workflow. You cannot commit to master. Focus on one feature and keep your branch short.

  1. branch out from master
  2. implement one thing
  3. if needed, periodically sync your branch with master using rebase onto master (do not merge - this produces very tangled Git history). See Git basics about rebasing.
  4. make pull request
  5. once your code is approved, merge (using the Github Merge button with creation of a merge commit). Ideally, rebase one last time before merging to produce a bow-shaped branch.

...rinse and repeat.

We have Github events (PRs open/close, issues) connected to #repo-notifications on Slack.

Squash before merge

Before merging your branch, it is advisable that you squash your commits into one, as described here.

You can do so after peer review.

Using GitHub Issues

Please use the provided templates and fill out your tickets thoughtfully. The main goal is to provide enough information for a complete stranger to be able to begin work on an issue without much personal consultation with other team members. This is especially important in a distributed, volunteer project such as ours.

  • Milestones: We use milestones to organize and easily filter high-level categories of work by area of functionality (equivalent to epics, for those familiar). We try to keep separate milestones for each team. Currently, we are working towards:
  • Labels: We use labels to categorize tasks thematically but not chronologically. Green labels identify which team the issue belongs to. Needs help indicates good first issues for newcomers to pick up. Needs detail indicates inadequate definition of the problem.
  • Documentation & decision-making: We use GitHub Issues and comments within specific issues to track specifications and decisions related to functionality. If a decision related to a specific piece of functionality is originally decided in Slack or in a meeting, please document that outcome in the related issue for posterity.

Issues are also prioritized using Project boards, of which we currently have 2:

If you are unable to access the project boards, make sure you’ve been added to our organization as described above.

If you see duplicated issues, obsolete issues, or issue dependencies or any other problems, please update them accordingly. Inform the team but do not hesitate to act.

Starting work on an issue

Issues marked with the yellow Needs help label are good first issues that you can jump in on as a newcomer.

Please assign yourself to an issue when you begin actual work on it. If you do not have time to work on it, do not assign yourself so that others know it is free for the taking.

Branch naming

It is advisable that you name your branch after the issue that it addresses, for example, it could be named:

issue_123_implement_motor_interface

This helps other team members understand the context for what you are working on without necessarily getting in touch with you.

You may also start working on things that are not defined in tickets, in which case keep your branch short but descriptive. However, carefully consider if it is not best to first define your problem in a ticket and document how it relates to existing issues, requirements or risks. It may be good to inform other team members of the implications of the problem you have spontaneously discovered.

Software documentation

Documentation on how to build and test the code is in the same directories as the code. Try to keep documentation close to the code that it explains. If you make changes that affect assumptions about hardware or build toolchain, make sure the relevant documentation is updated.

If you are implementing anything related to specific hardware, reference relevant datasheets or specification documents. Do so gratuitously, especially if there are firmware constants or other "magic numbers".

Code style

Agreements on Code Style are captured on this page.

Additional reading

Clone this wiki locally