183 lines
7.5 KiB
ReStructuredText
183 lines
7.5 KiB
ReStructuredText
Contributing to Boxes.py
|
|
========================
|
|
|
|
You are thinking about contributing to Boxes.py? That's great!
|
|
Boxes.py is designed to be re-used and extended.
|
|
|
|
This document gives you some guidelines how your contribution is most
|
|
likely to impact the development and your changes are most likely to
|
|
be merged into the upstream repository.
|
|
|
|
Most of them should be just general best practises and not be
|
|
surprising. Don't worry if you find them too complicated. It is OK
|
|
leave the final touch to someone else.
|
|
|
|
Writing code for Boxes.py
|
|
-------------------------
|
|
|
|
You will often be compelled to just do a quick thing that will solve
|
|
your immediate needs. That's fine. But nevertheless it is often worth
|
|
doing things the right way and be able to submit your changes
|
|
upstream. For one to give something back to the community. But also
|
|
for purely selfish reasons like getting the code maintained. Also
|
|
Boxes.py is designed to make doing things properly the easy way.
|
|
|
|
Here are some guidelines that make this easier. Depending on what you
|
|
are up to they may apply to a varying degree. It's ok to submit
|
|
patches that are not quite ready yet. But please state in the pull
|
|
request message what you think the status is and whether you want help
|
|
or are going to finish it on your own.
|
|
|
|
* Please fork the repository at GitHub before getting started
|
|
* Start with creating separate branches for each of your new generators or features
|
|
|
|
* You can merge them into your master branch to have them all in one place
|
|
* Please continue your work in the branches and repeatedly merge them to master
|
|
|
|
* Before submitting a pull request intended to go upstream have clean patches that are self contained and error free
|
|
|
|
* Re-order and squash patches with *git rebase -i*
|
|
* The patches should containing meaningful changes and not (necessarily) reflect how the code was created
|
|
* Rebase your branch to the current master branch
|
|
* Be prepared that your code may get reworked before being merged upstream
|
|
|
|
* Submit a pull request in GitHub based on your feature branch
|
|
|
|
* Describe the status of the patch set and your intentions with it in the pull request message
|
|
|
|
If you want to discuss your idea open a ticket describing it and ask
|
|
questions there. This is encouraged even if you think you know what
|
|
you want to do. There are many short cuts in Boxes.py and pointing you
|
|
in the right direction may save you a lot of work.
|
|
|
|
If you want feed back on you code feel free to open a PR. State that
|
|
this is work in progress in the PR message. It's OK if it does not
|
|
follow the guidelines (yet).
|
|
|
|
Check Code
|
|
..........
|
|
|
|
The `pre-commit <https://pre-commit.com/>`_ tool is used to verify the code style.
|
|
When installed, it automatically checks and corrects the code before each commit.
|
|
|
|
* Install *pre-commit*, e.g. :code:`pip install pre-commit`
|
|
* Install githook :code:`pre-commit install`
|
|
|
|
For manual check use :code:`pre-commit run --all-files`.
|
|
|
|
To remove githook use :code:`pre-commit uninstall`.
|
|
|
|
Writing new Generators
|
|
......................
|
|
|
|
Writing new generators is the most straight forward thing to do with
|
|
Boxes.py. Here are some guidelines that make it easier to get them added:
|
|
|
|
* Start with a copy of another generator or *boxes/generators/_template.py*
|
|
* Commit changes to the library in separate patches
|
|
* Use parameters with sane defaults instead of hard coding dimensions
|
|
* Simple generators can end up as one single commit
|
|
* For more complicated generators there can be multiple patches -
|
|
each adding another feature
|
|
|
|
Adding new Dependencies
|
|
.......................
|
|
|
|
Adding new dependencies should be considered thoroughly. If a new
|
|
dependency is added it needs to be added in all these places:
|
|
|
|
* *documentation/src/install.rst*
|
|
* RST files in *documentation/src/install/*
|
|
* *scripts/Dockerfile*
|
|
|
|
If it is a Python module it also needs to be added:
|
|
* *requirements.txt*
|
|
* *setup.py*
|
|
|
|
Improving the Documentation
|
|
---------------------------
|
|
|
|
Boxes.py comes with Sphinx based documentation that is in large parts
|
|
generated from the doc strings in the code. Nevertheless documentation
|
|
has a tendency to get outdated. If you encounter outdated pieces of
|
|
documentation feel free to submit a pull request or open a ticket
|
|
pointing out what should be changed or even suggesting a better text.
|
|
|
|
To check your changes docs need to be build with *make html* in
|
|
*documentation/src*. This places the compiled documentation in
|
|
*documentation/build/html*. You need to have *sphinx* installed for
|
|
this to work.
|
|
|
|
The online documentation gets build and updated automatically by the Github Actions
|
|
as soon as the changes makes it into the GitHub *master* branch.
|
|
|
|
Provide photos for generators
|
|
-----------------------------
|
|
|
|
Many generators still come without an example photo. If you are
|
|
creating such an item consider donating a good picture. You can
|
|
simply attach it to `ticket #628
|
|
<https://github.com/florianfesti/boxes/issues/628>`_. If you want you can
|
|
also create a proper pull request instead:
|
|
|
|
* Make sure you have sh, ImageMagick (You will need to install legacy utilities for convert), sed and sha256sum installed
|
|
* The picture needs to be an jpg file with the name of the generator
|
|
(This is case sensitive. Use CamelCase.)
|
|
* The picture should be 1200 pixels wide and square or not too far
|
|
from square (3:4 is fine).
|
|
* Minimize the file size by running it through `Tiny Png <https://tinypng.com/>`_
|
|
* Place the file in *static/samples/*
|
|
* Check if the picture shows up at the bottom of the settings page of
|
|
the generator when running *scripts/boxesserver*
|
|
* Change dir to *./scripts* and there execute *./gen_thumbnails.sh*
|
|
* Check if the thumbnail is seen in the main page when hovering over
|
|
the generator entry
|
|
* Create a commit including *static/samples/$GeneratorName\*.jpg* and
|
|
*static/samples/samples.sha256*
|
|
* Create a pull request from that
|
|
|
|
Improving the User Interface
|
|
----------------------------
|
|
|
|
Coming up with good names and good descriptions is hard. Often writing
|
|
a new generator is much easier than coming up with a good name for it
|
|
and its arguments. If you think something deserves a better name or
|
|
description and you can come up with one please don't hesitate to open
|
|
a ticket. It is this small things that make something like Boxes.py
|
|
easy or hard to use.
|
|
|
|
There is also an - often empty - space for a longer text for each
|
|
generator that could house assembling instructions, instructions for
|
|
use or just more detailed descriptions. If you are interested in
|
|
writing some please open a ticket. Your text does not have to be
|
|
perfect. We can work on it together.
|
|
|
|
Running the Code
|
|
----------------------------
|
|
|
|
To serve website, run :code:`scripts/boxesserver` script.
|
|
|
|
You can set the BOXES_GENERATOR_PATH environment variable to add
|
|
custom generators if you cannot easily copy them in the sources /
|
|
system installation.
|
|
|
|
Reporting bugs
|
|
--------------
|
|
|
|
If you encounter issues with Boxes.py, please open a ticket at
|
|
GitHub. Please provide all information necessary to reproduce the
|
|
bug. Often this can be the URL of the broken result. If the issue is
|
|
easy to spot it may be sufficient to just give a brief
|
|
description. Otherwise it can be helpful to attach the resulting SVG,
|
|
a screen shot or the error message. Add a "bug" tag to draw additional
|
|
attention.
|
|
|
|
Suggesting new generators or features
|
|
-------------------------------------
|
|
|
|
If you have an idea for a new generator or feature please open a
|
|
ticket. Give some short rational how or where you would use such a
|
|
thing. Try to give a precise description how it should look like and
|
|
which features and details are important. The less is left open the
|
|
easier it is to implement. You can add an "enhancement" tag.
|