Skip to content

Home

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

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 relevant 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 lead! :)
  • 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 it ensures:

  • strict version control
  • strict procedures for peer review
  • automated scripts that 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 it. This is also helpfully managed by GitHub (also explained below).

The goal 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.

Domain-specific info

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 notes Using KiCAD

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

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?

Unless you are doing CAD work and CAD work only, you will be working with text files.

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.

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. If in doubt, reach out to someone on the software team to confirm that your files are ok.

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"

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

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)
  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 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. If your PR is not software-related, you may remove the "code" section. The checklist will link to the Documentation style guide and Code style guide, either 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 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

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