Skip to content

Home

Jump to bottom
Martin Shetty edited this page Apr 21, 2021 · 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

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

Furthermore:

  • subscribe to our google calendar to see regular meeting times
  • bookmark our google drive - files can be viewed by all with a link, but edited only by members of organization

For more details you can review our general onboarding guide.

Once you receive an invitation to our Google Suite, please accept it and reconfigure your email address as described here.

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!
  • If you think you are sitting around with nothing to do and your talent is going to waste, say something. Or just take charge :)
  • Communicate ideas, obejctions and observations publicly -- whether in a slack channel (rather than private message), or in github tickets. This is so that ideas can easily be found by other contributors in the future.
  • 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 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. Changes to this page do not require review and approval.

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 (how to do this is explained below).

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.

Please set up git on your local machine before proceeding. Follow these instructions and then come back to this guide. If you are on linux or Mac, you must install git-lfs for the repository to clone correctly (additional notes).

If you are new to git, you might find this Cheat sheet useful.

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.

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

Binary files must use LFS

LFS is the "Large File System" for Git.

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"

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 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, 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:

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

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.

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.

  • 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 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 team. Milestones help us prioritize features for the upcoming prototype version. Here is our tentative versioning schema.
  • 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 are also 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.

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