General changes related to making repo public (#27)

* Update README.md * added version specification to requirements.txt * Create CONTRIBUTING.md * Create LICENSE * Update README.md * Update README.md * Update README.md * Update README.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * updated user guide * added cc-by-sa license text * Update CONTRIBUTING.md Co-authored-by: Ryan Bloom <Ryan.b.702@gmail.com> * changed version specification to ~= for everything except pyserial * updated pyproject.toml with new version specification --------- Co-authored-by: Ryan Bloom <Ryan.b.702@gmail.com>
ebbcarbon · Jun 7, 2024 · 7f3f2e8 · 7f3f2e8
1 parent 9ea80bc
commit 7f3f2e8
Show file tree

Hide file tree

Showing 7 changed files with 1,168 additions and 28 deletions.
diff --git a/CC-BY-SA b/CC-BY-SA
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,40 @@
+## Project Structure and Style
+- `lib`: top-level module. The main functionality of the package is kept here.
+- `services`: main modules comprising the backend of the system, e.g. serial clients and chemistry calculations.
+- `utils`: extra modules not considered to be core services.
+- `view`: modules defining the desktop user interface.
+
+Each module within these directories has a sub-directory called `tests` which stores unit tests for that module.
+
+We generally follow [PEP8](https://peps.python.org/pep-0008/), and prefer Google-style [docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) for Python code.
+
+## Issues and Feature Requests 
+If you find a bug, or want to request a new feature be added, submit these as an [issue](https://github.com/ebbcarbon/openalk/issues).
+
+## Submitting a Pull Request
+We follow a ["Gitflow"](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) development workflow, in which the `main` branch stores the latest release and the `develop` branch is used for active development.
+
+To contribute code, follow these steps: 
+- Fork the current state of the `develop` branch into your own repository 
+- Name your own branch with the schema `feature/<description>`, with the description being as short as possible while still clarifying what the branch contains.
+- Submit a [pull request](https://github.com/ebbcarbon/openalk/pulls) against this repository's `develop` branch from your `feature` branch.
+
+Any changes we merge will require pytest-compatible unit tests before being incorporated. See the section below for more information.
+
+## Unit Tests
+
+#### Pytest
+Pytest is a standard framework for unit testing in python applications. For more information about pytest, see the [pytest documentation](https://docs.pytest.org/en/8.2.x/).
+
+See any of the `tests` sub-directories (e.g., [here](lib/services/pump/tests)) for examples of how these tests are written.
+
+You can run the test suite yourself to see what it looks like: if on Linux, run the command `make test` from the repository's toplevel directory; if on Windows, activate the virtual environment and run the command `python -m pytest` from the same location.
+
+#### Test Naming Requirements
+* In order for your unit tests to be run, two naming conventions must be followed
+    1. File names: must end with `_test.py`. Only files that end with `_test.py` will be collected and found by pytest.
+        * We will follow the format of copying the name of the file to be tested and appending `_test.py` to that.
+        * Example: In order to test a file named `new_feature.py`, there will be a corresponding test file named `new_feature_test.py`
+    2. Test names: must start with `test_`. In order for individual test methods to be found by pytest, they must start with `test_`.
+        * To test the happy path for a method named `my_method()`, you could write a test called `def test_my_method__success()`.
+        * To test the sad path for that same method, you could write a test called `def test_my_method__fails()`.
diff --git a/LICENSE b/LICENSE
diff --git a/README.md b/README.md
@@ -2,19 +2,17 @@
 
 [![Tests](https://github.com/ebbcarbon/openalk/workflows/Tests/badge.svg)](https://github.com/ebbcarbon/openalk/actions)
 
-## Unit Tests
-Each service/utils directory should have a `tests` sub-directory. Within this `tests` sub-directory, there should be multiple unit test files corresponding to their services.
+OpenAlk is a low-cost system for measuring total alkalinity of seawater samples utilizing a combination of off-the-shelf hardware and open-source software, meant to increase the convenience, speed, and accessibility of alkalinity measurement. The system generally follows the process outlined in Dickson [SOP 3B](https://www.ncei.noaa.gov/access/ocean-carbon-acidification-data-system/oceans/Handbook_2007.html) for determining alkalinity by open-cell titration, and is fully automated aside from requiring some experimental setup steps from the user.
 
-ALL new pull requests and logic changes should come with unit tests to confirm these changes work. Development work is NOT complete without unit tests.
+## User Guide
+Instructions for setting up the hardware and installing the software can be found in the [user guide](docs/userguide.pdf), along with
+SOP documents detailing basic benchtop usage and a bill of materials (BOM) showing what you'll need to get started.
 
-#### Running test suite
-To run all unit tests (that are named correctly in correspondence with the naming requirements outlined below), simply run `pytest` command from the base directory in your terminal.
+## Feature Requests, Issues, and Pull Requests
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more info on how to submit an issue, request a feature be added, or contribute your own code. 
 
-#### Test Naming Requirements
-* In order for your unit tests to be run, two naming conventions MUST be followed
-    1. File names: MUST END with `_test.py`. Only files that end with `_test.py` will be collected and found by pytest.
-        * We will follow the format of copying the file to be tested's name and appending `_test.py` to that.
-        * Example: In order to test a file named `my_service_file.py`, there will be a corresponding test file named `my_service_file_test.py`
-    2. Test names: MUST START with `test_`. In order for individual test methods to be found by pytest, they must start with `test_`.
-        * To test the happy path for a method named `my_method()`, you could write a test called `def test_my_method__success()`.
-        * To test the sad path for that same method, you could write a test called `def test_my_method__fails()`.
+We welcome any suggestions for how to improve the system, and encourage you to raise any issues you find!
+
+## License
+The software portion of this project is licensed under a [GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html) license, the design documents and instructions are licensed
+under a Creative Commons [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0) license.
diff --git a/docs/userguide.pdf b/docs/userguide.pdf
diff --git a/pyproject.toml b/pyproject.toml
@@ -22,13 +22,13 @@ maintainers = [
 
 dependencies = [
     "pyserial>=3.5",
-    "numpy>=1.26.4",
-    "matplotlib>=3.8.4",
-    "flake8>=7.0.0",
-    "black>=24.4.1",
-    "pytest>=8.1.1",
-    "pytest-cov>=5.0.0",
-    "pep8-naming>=0.13.3"
+    "numpy~=1.26.4",
+    "matplotlib~=3.8.4",
+    "flake8~=7.0.0",
+    "black~=24.4.1",
+    "pytest~=8.1.1",
+    "pytest-cov~=5.0.0",
+    "pep8-naming~=0.13.3"
 ]
 
 [project.urls]

diff --git a/requirements.txt b/requirements.txt
@@ -1,8 +1,8 @@
-pyserial
-numpy
-matplotlib
-flake8
-black
-pytest
-pytest-cov
-pep8-naming
+pyserial>=3.5
+numpy~=1.26.4
+matplotlib~=3.8.4
+flake8~=7.0.0
+black~=24.4.1
+pytest~=8.1.1
+pytest-cov~=5.0.0
+pep8-naming~=0.13.3