diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 960617b..e35f0f7 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -6,7 +6,7 @@ assignees: '' --- - **Description of the bug** diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac9d047..101436b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,28 +1,48 @@ -### Hey there! So you've decided to contribute to the plugin. Here's what you need to know. +# Contribution Guidelines -Please take note of the few things below for contributing to the plugin, it's not extensive and designed to make contributions as smooth as possible +First, thank you for considering contributing to this project! -- Please only create pull requests against: - - `maintenance` for bug fixes or improvements - - `devel` for new features - - Never `master`, as this is downloaded by users so must remain untouched until release. (EXCEPTION: Documentation, like this) -- If your changes are large or disruptive, please open an issue first to dicuss. There may be things in the pipeline that would conflict -- Read the detail below so you understand how the plugin works! +The guidelines here aim to make it as smooth as possible for contributors to understand how to contribute, what they can contribute +and how the plugin works. -### How does it work? +There's a couple of things to consider before making your contribution: -This plugin is currently written with 2 layers: +- Please create pull requests against the `devel` branch unless indicated otherwise. + There is an exception to this rule: documentation. See more below. -- The OctoPrint plugin class, -- The effect runner class. +- If your changes are large or disruptive, please open an issue first so that we can discuss. I don't want you to put in a lot + of work only for it to end up going to waste as there were already different plans. -When a user starts the plugin, OctoPrint loads the plugin class. This spins off a new process of the effect runner class, which handles driving the LEDs +- Read the additional points below for details on code style, testing and how everything fits together. -Operating flow goes a bit like this: +### Documentation -- Event recieved by the plugin class (This may be an OctoPrint event, gcode command or pressing the on/off button.) -- Evaluated, and decide what to do happens plugin side. Message constructed -- Message put in a queue through to the effect runner class. Any active effect is stopped immediately and message is read -- Analyse message, and decide what effect to run +Contributing documentation changes is easy, since everything is formatted using markdown. The docs are built from +the `docs` sub folder by GitBook, hosted at https://cp2004.gitbook.io/ws281x-led-status/. -All effects are kept in the sub-module `effects`, while there are useful functions that can be called cross module in the `util.py` file +For the documentation for the current release of the plugin, please make it against the branch labelled for the minor version. (Currently `0.7.x`) +This means that I can keep them versioned and not break things between releases. + +When contributing additional features or configuration please try to document it where necessary, however do not put +off your contribution because you are struggling to document it! + +### Code style + +The plugin has a pre-commit setup that runs black, prettier, isort and various other code-mods. + +You can either set this up as a file watcher [as in the PyCharm example in OctoPrint's documentation (under pre-commit)](https://docs.octoprint.org/en/master/development/environment.html#pycharm). + +You can also run this as a one-off using `pre-commit run --hook-stage manual --all-files`. + +### Testing + +Running the unit tests is simple, though they require additional dependencies. + +If you installed OctoPrint in a development environment, using `pip install octoprint[develop]` or `pip install -e .[develop]` (in the checkout) +these are already there. Otherwise, install them using `pip install pytest mock` + +Run it: `pytest` (or `python -m pytest`) + +### Anything else? + +Nothing else important! Give your PR a suitable description and let me merge it :) diff --git a/README.md b/README.md index 9edaa91..fe062f2 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Add some RGB LEDs to your 3D printer for a quick status update! A highly configurable plugin for supporting WS2811, WS2812 and SK6812 LEDs attached to your Raspberry Pi. -With lots of effects to choose from, you can customise the plugin to do things _exactly_ as you want them, to display the status from your 3D printer from a simple strip of LEDs +With lots of effects to choose from, you can customise the plugin to do things _exactly_ as you want them, to display the status from your 3D printer from a simple strip of LEDs. Features include: @@ -14,9 +14,9 @@ Features include: - Tracking heating & printing progress - Intercepting M150 commands - Quick on/off button from the navbar -- 'Torch' button -- A timer to turn the LEDs on or off at certain times -- Easy to use but highly configurable settings interface, you can turn pretty much anything on or off. +- 'Torch' function, to light up your printer +- A timer to turn the LEDs on or off at certain times of day +- Easy to use but highly configurable settings interface, you can turn pretty much anything on or off and configure it to how you like it. - LED Strip test - Power calculator - ... and more! @@ -35,7 +35,7 @@ Setting up the plugin couldn't be easier! There are 3 main steps, with the heavy Follow the detailed [setup guide](https://cp2004.gitbook.io/ws281x-led-status/guides/setup-guide-1) in the documentation to get up and running. -### Getting help +## Getting help Please read the [Get Help Guide](https://cp2004.gitbook.io/ws281x-led-status/guides/get-help-guide) as well as the [rest of the documentation](https://cp2004.gitbook.io/ws281x-led-status/), to see if your question has been answered there. Still got questions? Get in touch: @@ -43,11 +43,17 @@ Please read the [Get Help Guide](https://cp2004.gitbook.io/ws281x-led-status/gui - On the [Community Forums](https://community.octoprint.org) - Open an issue with the [question template](https://github.com/cp2004/OctoPrint-WS281x_LED_Status/issues/new?assignees=&labels=type%3A+question&template=question.md&title=) -### Reporting problems +## Reporting problems Whilst I don't like bugs, I want to hear about them! Let me know by [opening an issue](https://github.com/cp2004/OctoPrint-WS281x_LED_Status/issues/new?assignees=&labels=type%3A+potential+bug&template=bug_report.md&title=%5BBug%5D) -# Support my work! +## Contributing + +I accept many forms of contribution, from fixing bugs, documentation and new features. +Please see the [Contributing Guidelines](https://github.com/cp2004/OctoPrint-WS281x_LED_Status/blob/master/CONTRIBUTING.md) for more details or get +in touch if you don't know where to start. + +## Support my work! I created this plugin in my spare time, so if you have enjoyed using it then please [support it's development!](https://github.com/sponsors/cp2004) @@ -55,8 +61,10 @@ I created this plugin in my spare time, so if you have enjoyed using it then ple ## Thanks +This was my first plugin and still my favourite, I have to say thanks for helping me develop it: + [jneilliii](https://github.com/jneilliii) for always answering my questions on discord, and making great plugins I could use as examples. -Andreas C. for jumping at the opportunity to beta-test, and providing great feedback! +Andreas C. for jumping at the opportunity to beta-test, and providing great feedback as I was creating this! -And, of course, [Gina Häußge](https://github.com/foosel) for creating OctoPrint +And, of course, [Gina Häußge](https://github.com/foosel) for creating OctoPrint and such a great community around it.