Contributing - guydavis/machinaris GitHub Wiki

Thank you for taking the time to contribute!

Suggesting a feature

We can't think of everything. If you've got a good idea for a feature, then please let us know!

Feature suggestions are embraced, but will often be filed for a rainy day. If you require a feature urgently it's best to write it yourself. Don't forget to share ;)

When suggesting a feature, make sure to:

  • Check the code on GitHub to make sure it's not already hiding in an unreleased version ;)
  • Considered if it's necessary in the library, or is an advanced technique that could be separately explained in wiki documentation.
  • Check existing issues, open and closed, to make sure it hasn't already been suggested

Filing a bug report

If you're having trouble with Machinaris try asking on our Discussions (https://github.com/guydavis/machinaris/discussions) or Discord (https://discord.gg/mX4AtMTt87). Feel free to submit fixes for documentation too, not just bugs!

If all else fails then please raise an Issue to let us know. Be as detailed as possible, and be ready to answer questions when we get back to you. Make sure you include your system setup:

  • OS: [e.g. Ubuntu, Windows, MacOS, Unraid, etc]
  • Docker version number (output of docker info)
  • Machinaris branch: main/test/develop (you're probably on main)
  • Machinaris version number (see bottom of every Machinaris page)

Setting up a development environment

This is my approach to using Visual Studio Code to develop Machinaris in-container, using a volume to mount editable code. There are other ways to do this, but it works for me!

  1. Install Machinaris on a Windows, Linux, MacOS, Unraid, etc system.
  2. Then fork the Machinaris repository using your own Github account.
  3. Git clone your fork to your development system. It can be the system running Machinaris in step #1 or it can be a laptop with file access to that system (network share for example).
  4. In that repo, switch to the "integration" branch to base your changes upon. You can change the branch, using Visual Studio Code, after opening the folder.
  5. Restart Machinaris, but this time add a volume mount named /code/machinaris like this: -v /path/to/checkout:/code/machinaris. This will ensure the checked out code of the integration branch is now available inside the Machinaris container at /code/machinaris.
  6. Run the following to stop Machinaris running against the original bundled code: /machinaris/scripts/stop_machinaris.sh
  7. In a shell, enter the container with docker exec -it machinaris bash, then cd '/machinaris', and ./scripts/dev/start-web.sh -> This will start the Machinaris WebUI running in the foreground against your code in '/code/machinaris' path.
  8. In another shell, enter the container with docker exec -it machinaris bash, then cd '/machinaris', and ./scripts/dev/start-api.sh -> This will start the Machinaris API server running in the foreground against your code in '/code/machinaris' path.

You can now make changes to the code you checked out. A simple Control-C in either shell, up-arrow, then run either start-xxx.sh will reload your changes. Then just refresh your browser pointed to http://localhost:8926 to see the changes.

Once you have some changes you would like to propose as a pull request, please follow the Github giude and see below.

Updating Translations

For Localization, if you would like to update the translation files:

docker exec -it machinaris bash
cd /code/machinaris
./scripts/i18n/extract.sh
... edit the messages.po files in /code/machinaris/web/translations (for example)...
./scripts/i18n/extract.sh

Then restart the WebUI in another shell with:

docker exec -it machinaris bash
cd /machinaris/
./scripts/stop_machinaris.sh
./scripts/dev/start-web.sh

At same time, run the API server too in another shell:

docker exec -it machinaris bash
cd /machinaris/
./scripts/dev/start-api.sh

Then browse to the WebUI and you should see your updated translations.

Submitting a pull request

If you've decided to fix a bug, even something as small as a single-letter typo then great! Anything that improves the code/documentation for all future users is warmly welcomed.

If you decide to work on a requested feature it's best to let us (and everyone else) know what you're working on to avoid any duplication of effort. You can do this by replying to the original Issue for the request.

If you want to contribute an example; go for it! We might not always be able to accept your code, but there's a lot to be learned from trying anyway and if you're new to GitHub we're willing to guide you on that journey.

When contributing a new example or making a change to a library please keep your code style consistent with ours. We try to stick to the pep8 guidelines for Python (https://www.python.org/dev/peps/pep-0008/).

Do

  • Do fork the project and work off the integration branch.
  • Do use pep8 style guidelines
  • Do comment your code where necessary
  • Do submit only a single example/feature per pull-request
  • Do include a description of what your change is expected to do
  • Do include the new API calls by updating the Postman collection

Don't

  • Don't include any separate license information in your change - our repo is Apache licensed
  • Don't try to do too much at once - submit one feature/fix at a time, and be receptive to feedback

Licensing

When you submit code to our libraries, you implicitly and irrevocably agree to adopt the associated licenses. You should be able to find this in the file named LICENSE.

We use the Apache license; which permits Commercial Use, Modification, Distribution and Private use of our code, and therefore also your contributions. It also provides good compatibility with other licenses, and is intended to make re-use of our code as painless as possible for all parties.

You can learn more about the Apache license: https://www.apache.org/licenses/LICENSE-2.0

Submitting your code

Once you're ready to share your contribution with us you should submit it as a Pull Request.

  • Be ready to receive and embrace constructive feedback.
  • Be prepared for rejection; we can't always accept contributions. If you're unsure, ask first!

Thank you!

If you have any questions, concerns or comments about these guidelines, please get in touch.