Skip to content

Home

Jump to bottom
Martin Shetty edited this page Jul 8, 2022 · 105 revisions

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

Please read this whole page 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

To start working with us, take these steps first:

  • Mail us at join-us@respira.works to receive an invitation to our Slack chat rooms.
  • Subscribe to our Google calendar and Google drive as described in our Google suite guide.
  • Sign up with GitHub and tell us your username, so we can add you to our organization.
  • Introduce yourself in the #general channel once you join Slack. Tell us something about your background and area of interest, so we can ping the relevant people to get you up to speed.
  • When you have time, fill out the new volunteer form . This will help us set up a bio for you on our website, and make sure you're credited for your contributions to the project.

You may need to come back to this section as you receive invitations to all the tools, so you can finish setting them up correctly. Meanwhile, you can continue reading about how we collaborate...

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, don't be afraid to say it!
  • Communicate ideas, objections and observations publicly -- in the relevant Slack channel (rather than private message), and in GitHub issues. This is so that ideas can easily be found by current and future contributors.
  • Stay hydrated and try to have fun!

Purpose of this wiki

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

The wiki should not contain technical content, such as requirements, design or engineering decisions. We want to explicitly track those with full version control.

Otherwise, please feel free to add any helpful information to this guide. Changes to the wiki pages do not require peer review.

Purpose of repository

In case you are new to git and GitHub - git is a version control system mainly popular with but not restricted to software projects.

We are using git to track the entirety of our ventilator design - requirements, mechanical, electrical design, software, testing protocols. The totality of this information constitutes a "repository", a project that is hosted here by GitHub. GitHub also provides this wiki and an issue tracking system.

We want to enable anyone on the planet to build the ventilator based on the information provided in this repository. Until the design is "complete", the repository must represent whatever is the latest state of our prototype design.

Somewhat uniquely among git projects, we track a lot of non-software content, 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:

  • documentation defines the design, so its evolution must be tracked
  • git ensures strict version control
  • git ensures strict procedures for peer review
  • automated scripts periodically check the validity of all links

If there is anything potentially helpful to building or testing a prototype or any of its components, please add this information to the repository (how to do this is explained below).

If you discover a potential problem in the design, or you think a feature is missing, you should create an issue (i.e. ticket) that will allow us to formally discuss and decide on how to handle the problem. These tickets are also helpfully managed by GitHub (also explained below).

One goal of the documentation is maximum visibility and discoverability by all possible collaborators, including ones from outside 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

If you are contributing to the project in a technical capacity - whether software, mechanical, electrical or even requirements and regulatory documentation - you will likely need to use git. An exception might be project management, where you might get by just working with tickets via the web-interface.

Please set up the git software tool and make a local copy of the repository on your computer before proceeding. Follow instructions on the git setup page and then come back to this guide. If you are new to git, you might find the git cheat sheet useful.

Will you work with text files?

Even if you are working on CAD or electronics, you will likely need to write up some verbal documentation.

If you intend to edit any text files, such as code, requirements or other documentation, you should install pre-commit and activate it for this repository. Otherwise, your changes may not pass automatic checks for merging. For details, please see the Pre-commit hooks page.

Most documentation is kept in "markdown" format. Avoid uploading any PDFs or word-processor files. Markdown is a simple HTML-like language for drafting documentation, such as this page. If this is new to you, see the Markdown basics page. For more info also see the Documentation style guide.

Will you work with binary files?

Binary files are everything other than plain text files. If you are working with mechanical or electrical engineering, or if are making any graphics, pictures, drawings or illustrations, these are all binary files.

Mostly you have nothing to worry about, except beware that any new binary file types must be added to the "large file" filter. File types that are by default added to "large file system" (LFS) are listed in .gitattributes at the repository root. If you are introducing a new file type that is not already covered, you can add it to the filter by running something like:

git lfs track "*.psd"

Read more about Large File System here.

Still, you should take care to not commit excessively large files. Some file types, such as exported STEP files, PDFs or full-resolution photos should be avoided. Anything that does not strictly define the design of the ventilator should instead be saved to our Google Drive. For more info see the Documentation style guide.

Domain-specific standards

While you should read the rest of this guide and learn how we collaborate, you may be itching to jump into reviewing content that is most pertinent to your area of expertise.

Without further ado:

Software Mechanical Electronics
Code style Mechanical engineering standards Using KiCAD

Now that you are no longer starving, you should continue with the rest of this guide...

Issues and tasks

We use GitHub's issues feature to organize and track our work. Issues may alternatively be referred to as "tickets" or "tasks".

  • Templates and detail: When creating an issue, 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. If you are unable to provide enough detail, please tag the issue with the Needs detail label.
  • Documentation & decision-making: We use issues and comments within 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 permanence and discoverability. Once a technical decision is finalized, the outcome should be committed as changes to the repository itself - either as code in case of software, or as mechanical design specification documents. Only then is an issue considered closed.
  • 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 discipline/area of work. Milestones help us prioritize features for the upcoming prototype version. Here is our tentative versioning schema for how we number prototype versions.
  • 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. As a newcomer with unique experience and specialization, you may also be able to fill out some of those missing details.

Issues can also be prioritized using Project boards, of which we currently have 4:

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. For more details see the project management guidelines

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. Better yet, check with others on the team on what would be most helpful at the moment.

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. There is no shame in un-assigning. Honesty is gold.

Workflow

Git is a strict versioning system that allows us to institute a specific procedure for how we adopt proposed changes to our product design or functionality.

We follow what is known as "trunk" workflow. You cannot commit to the master (main) branch. 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 rebasing for more information.
  4. make a pull request (request for peer review, more on this below)
  5. once your contribution 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. Subscribe to this channel to stay aware of new issues, new pull requests and recently merged changes.

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.

Design review

We are creating a life-critical medical device. Rigorous design and code review is essential for quality assurance. The mechanism for ensuring this is a "git pull request". This terminology is somewhat confusing. It may more appropriately be called a "merge request", because you are asking your colleagues to review your contributions to be merged into the "main" branch of the repository. The term "pull request" is, however, ubiquitous in the world of git and features prominently in the GitHub web interface, so we will continue calling it a "pull request".

You can create a pull request (henceforth: PR) from within the GitHub web interface after finding your branch here. Please follow the PR template's checklist. You may delete checklists unrelated to your content. The checklist will link to the Documentation style guide, Code style guide and Mechanical engineering standards some of which you may want to get familiar with already.

Each 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 those same files, or ask around on Slack.

If you are a reviewer, and you notice a nitpicky fix, such as a typo, you can suggest an edit rather than spending time describing the problem to the author verbatim. This will save time.

If a reviewer makes a comment or request for changes, try to 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 automatic tests 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.

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

Just before merging, you MUST manually rebase-squash your branch, particularly if you have contributed to mechanical/CAD design or have changed any binary files, such as graphics. This is to keep our repository from bloating and increasing our server bandwidth costs.

Continuous integration

Continuous integration refers to automated error checks that are performed on all contributions to the repository.

This includes:

  • broken 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.

Additional reading

Clone this wiki locally