Update readme and contributing files (#158)

* Updated README.md with slight changes and CONTRIBUTING.md with the template from minerva-rewrite

* Fixed typo

Author: Darth-Raazi

CONTRIBUTING.md

@@ -1,31 +1,39 @@
-# Contributing
-Welcome to Omnibus! To get started, follow these steps:
+# Contributing to Omnibus
 
-1. Clone this repo.
-    * If you have git configured with SSH, run `git clone [email protected]:waterloo-rocketry/omnibus.git`
-    * If you don't have git configured with SSH (or you're not sure what that means), run `git clone https://github.com/waterloo-rocketry/omnibus.git`
-2. Enter the newly-cloned repo with `cd omnibus`
-3. Run `pip install wheel`, which will help install the rest of the packages more quickly.
-4. Install Python dependencies with `pip install -r requirements.txt`. If you get a permissions error, try `pip install --user -r requirements.txt` instead.
-5. Install the Omnibus library locally with `pip install -e .`. Don't forget the `.`! This allows the sources and sinks (and you) to import Omnibus.
+## Setting Up Your Environment
 
-You should now be ready to start developing!
+### Cloning the Repo and Installing Dependencies
 
-* To run unit tests: `pytest`
-* To launch the Omnibus server: `python -m omnibus`
-* To run a source/sink: `python sources/name/main.py`
+Please follow the steps listed in the [README](https://github.com/waterloo-rocketry/omnibus/blob/master/README.md#installation).
 
-# Style guide
-If you'd like to contribute to Omnibus, please take a moment to read through this style guide. Otherwise, happy devving :)
+## Contributing Code
 
-### Python
-We generally conform to [PEP8](https://pep8.org/) guidelines for how we format our Python code. The repository contains a custom formatting script (`tools/format.sh`) - you should run this optionally before commits, and definitely before creating pull requests and/or merging to master.
+### Taking Issues
 
-When adding code, make sure to add unit tests to match! It's generally a good idea to run the full suite of unit tests before creating a PR (which can be done with the `pytest` command). If you don't, CI will run it for you, but it'll take much longer. We'll get a Slack notification if a failing build makes it to master (but this is fairly unlikely), so don't be too scared of breaking things. They're always fixable :).
+The best way to get started on contributing to Omnibus is to take on an issue. Simply go to the [Software Master Project](https://github.com/orgs/waterloo-rocketry/projects/2), expand the Omnibus section and find an unassigned issue that interests you. Some issues may be lacking context or background info so feel free to DM the current Software Lead or whoever opened the issue for some more info. Once you've found an issue that you would like to work on, then set yourself as the issue's assignee and once ready, change the status of the issue from "Todo" to "In Progress".
 
-### Git
-Generally, commit messages should follow guidelines laid out by Chris Beams [here](https://chris.beams.io/posts/git-commit/). Additionally,
-* Pull requests should be squashed and merged to be added as commits to master. If the PR pertains to code inside the `omnibus/`, `sources/` or `sinks/` directories (_not_ the main repo), the commit message should be of the form `<subsystem>: <Commit message> (#XX)`, where `<subsystem>` is the folder that the code is relevant to and `XX` is the PR number. `<Commit message>` is the commit message as normal, following regular message guidelines (capital first letter, no period, etc).
+### Creating Branches
 
-    An example commit message could be `plotter: Add custom dashboards (#42)`, for a PR that affects code inside the `sinks/plotter/` directory.
-    Commit messages for code outside the `omnibus/`, `sources/` or `sinks/` directories don't need to follow this format. This is mainly to ensure that changes are immediately recognizable reading commit messages from the top level of the repository.
+The repo follows the branch naming convention of `{name}/{issue_num}-{description}`, e.g. `oraazi/157-update-readme-contributing`
+
+- `{name}` is the part of the branch name that identifies its author. Please use your **WatIAM username** (the combination of your first intial, possibly some numbers, and the first few letters of your last name that comes before `@uwaterloo.ca` in your email).
+- `{issue_num}` is the issue number of the issue that you are trying to fix or implement. If this branch is not associated with an issue, then you do not need to specify anything for this (e.g., just `oraazi/update-readme-contributing` is fine)
+- `{description}` is a short description of what this branch is fixing/implementing. Be sure to keep it short, as good practice is to keep the entire branch name under 30-40 characters.
+
+### Formatting and Linting Your Code
+
+This repo conforms to [PEP8](https://pep8.org) guidelines for Python code. We have a script to automatically enforce these guidelines (`tools/format.sh`). It is **mandatory** to run this before pushing your branch or opening a PR, and *recommended* before every commit.
+
+### Publishing PRs
+
+When you have written up your code and are ready to get it revieweda and merged to `master`, then you can [open a PR for your branch](https://github.com/waterloo-rocketry/omnibus/compare). Here's a few things that you should make sure to do when creating your PR:
+
+- All branches being merged to `master` must pass all their unit tests (they are run automatically when you open a PR).
+- Assign yourself as the assignee for the PR.
+- Assign the `omnibus-reviewers` team as a reviewer for your PR. This will assign the people in charge of Omnibus as reviewers. Additionally, if desired, assign others as reviewers to the PR if you want them specifically to review it or if the reviewer is not in the `omnibus-reviewers` team.
+- Make sure to link the PR to the relevant issue, if possible. The easiest way is [by using keywords in the PR description](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword), e.g. you can link the PR to Issue 157 by writing "closes #157" somewhere in the description.
+- Since your task is now in a review state, make sure to move the project status of the issue that this PR is linked to from "In Progress" to "Needs Review". If this project is not linked to an issue, add the PR to the "Software Master Project" Project under Omnibus and set its status accordingly.
+
+### Merging PRs
+
+Once your PR has passed all unit tests, and has been reviewed and approved, you can merge it to `master`. Merge using the "Squash and Merge" option so that all the commits from your branch are "squashed" into one commit containing all the changes. Congrats, you're now free to take on another issue and continue to make Omnibus better! 

README.md

@@ -1,35 +1,46 @@
-## Omnibus
+# Omnibus
 
-Omnibus is a unified data bus which manages the connection of various data sources (such as DAQ, RLCS, and live telemetry) and sinks (such as plotting software and logging).
+## Omni-what?
 
-#### Requirements
+Omnibus is a unified data bus which manages the connection of various data sources (such as DAQ, RLCS, and live telemetry) and sinks (such as plotting software and logging). Basically, it allows us to take data input from a bunch of different sensors, broadcast it over Wi-Fi, and then display/store it in different formats on the receiving end. This is extremely useful during testing (such as cold flows and static fires) when we need real-time data updates from our test rig while being a safe distance away.
 
-Python 3.10 or newer is required. For Linux users, a python package with C headers (such as `python3-dev`) is necessary. 
+## Setup
 
-Required Python packages can be installed using `pip install -r requirements.txt`.
+### Requirements
 
-#### Installation
+Python 3.10 or newer is required. For Linux users, a python package with C headers (such as `python3-dev`) is necessary. 
 
-The Omnibus library is required to run any of the sources or sinks. To install it:
+### Installation
 
 1. Clone this repo.
-    * If you have git configured with SSH, run `git clone [email protected]:waterloo-rocketry/omnibus.git`
-    * If you don't have git configured with SSH (or you're not sure what that means), run `git clone https://github.com/waterloo-rocketry/omnibus.git`
+   - If you have git configured with SSH, run `git clone [email protected]:waterloo-rocketry/omnibus.git`
+   - If you don't have git configured with SSH (or you're not sure what that means), run `git clone https://github.com/waterloo-rocketry/omnibus.git`
 2. Enter the newly-cloned repo with `cd omnibus`
 3. Create a virtual environment:
-   - For osx/linux: `python -m venv venv`
-   - For windows: `python -m venv venv`
+   - First install the virtualenv library: `pip install virtualenv`
+   - Create the venv: `python -m venv venv`
 4. Activate the virtual environment:
    - For osx/linux: `source venv/bin/activate`
    - For windows: `venv\Scripts\activate`
 5. Upgrade pip version: `pip install --upgrade pip`
-6. Run `pip install wheel`, which will help install the rest of the packages more quickly.
-7. Install Python dependencies with `pip install -r requirements.txt`. If you get a permissions error, try `pip install --user -r requirements.txt` instead.
-8. Install the Omnibus library locally with `pip install -e .`. Don't forget the `.`! This allows the sources and sinks (and you) to import Omnibus.
+6. Run `pip install wheel`, which will help install the rest of the packages more quickly
+7. Install Python dependencies with `pip install -r requirements.txt`. You'll also need to run that command in each of the following folders:
+   - `sources/ni/`
+   - `sources/parsley/`
+   - `sinks/dashboard/`
+   - If you get a permission error, try `pip install --user -r requirements.txt` instead.
+8. Install the Omnibus library locally with `pip install -e .`
+   - Don't forget the `.`! This allows the sources and sinks (and you) to import Omnibus
 9. Initialize the `Parsley` submodule with `git submodule update --init --recursive` and install the library locally with `pip install -e ./parsley`
 
-#### Usage
+## Usage
+
+Omnibus works by running sources (to send data), sinks (to receive data) and a server to connect them together.
+
+### Server
+
+Start the Omnibus server by activating your `venv`, then running `python -m omnibus`.
 
-Omnibus requires a server to connect the sources to the sinks. To run the server, run `python -m omnibus`. You may now independently start the sources and sinks by running something like `python sources/name/main.py`.
+### Sources/Sinks
 
-*Note:* Sources/sinks may have their own `requirements.txt`.
+Depending on your configuration, you'll need to run one or more sources or sinks. Each one is started independently in the same way: `python sources-or-sinks/name/main.py`. For example, you can start the Dashboard by running `python sinks/dashboard/main.py`.