Skip to content

Latest commit

 

History

History
119 lines (88 loc) · 3.4 KB

CONTRIBUTING.md

File metadata and controls

119 lines (88 loc) · 3.4 KB
Raw

Contributing

Note that I will probably not have time to get to many issues or pull requests. I will try to fix bugs as quickly as I can and answer questions, but the other ones are not as prioritized.

Submitting an Issue

Before you submit an issue, make sure that your issue was not already submitted by someone else and is still open.

Otherwise, follow the issue template.

Submitting a Pull Request

Make sure you have an Arduino and the Arduino IDE installed before contributing.

First time setup:

  1. Download and install Git
  2. Configure git with username and email
> git config --global user.name 'your name'
> git config --global user.email 'your email'
  1. Fork the repository
  2. Clone the repository fork
> git clone https://github.com/{name}/COM-Server.git
> cd COM-Server
  1. Add the fork as a remote named fork
> git remote add fork https://github.com/{name}/COM-Server
  1. Create a virtualenv named .env
> python -m venv .env
  1. Install development dependencies and install the package in development mode
> pip install -r requirements.txt && pip install -e .
  1. Upload the script named send_back provided in the examples directory onto the Arduino.

Developing:

  1. Create a new branch
    • Off the 0.2.x branch if bug fix/docs fix
    > git fetch
> git checkout -b branch-name origin/0.2.x
    • Off the develop branch if adding feature
    > git fetch
> git checkout -b branch-name origin/develop
  2. Make changes and commit for each change
  3. Add tests that apply to your change
  4. Push your commits.
> git push -u fork branch-name
  1. Open a PR into develop if adding a feature or into 0.2.x if addressing a bug fix or a documentation fix.

NOTE: In the pull request, please specify the operating system and serial device (e.g. Arduino UNO, Arduino Mega, etc.) you tested COM-Server on.

> com_server --version

Testing:

Launch the server:

> com_server run <baud> <serport>

Replace "<baud>" and "<serport>" with the baud and serial port of your serial device.

Use the testing scripts:

> python3 tests/passive_test.py -vv
> python3 tests/active_test.py -vv

Make sure that all tests pass.

Some tests need the com_server command to be run or the Arduino to be plugged in. Make sure to run both commands above and also ensure that the Arduino is plugged in.

When writing tests, use the pytest library, and make them as specific as possible, testing a specific part of what you are making. Tests that do not require a serial port or a server should go into the tests/passive directory, and tests that do require an Arduino should go into the tests/active directory.

I am also open to those who write new tests to already existing code.

Typing:

If writing code in the src/com_server directory, please use mypy to check static typing by running:

> mypy -p com_server

Formatting:

Please format your code using Black.

Building documentation

COM-Server uses mkdocs for its documentation. To build the documentation:

> mkdocs build

To serve the documentation on localhost:8000

> mkdocs serve

Make sure to update the documentation to reflect your changes if there were any in the library.