docs/contributing/contributing.rst

============
Contributing
============

Please read the `code of conduct <https://github.com/dagworks-inc/burr/tree/main/CODE_OF_CONDUCT.md>`_
prior to contributing. Then follow these guidelines:

#. Create a fork of the repository.
#. Ensure all tests pass.
#. Make a PR to the main repository.
#. Ping one of the maintainers to review your PR.

-----------------------
Contribution guidelines
-----------------------

Please:

#. Keep your commits modular
#. Add descriptive commit messages
#. Attach a PR to an issue if applicable
#. Ensure all new features have tests
#. Add documentation for new features

Examples
--------

All examples must have the following files:
1. A ``README.md`` file that describes the example -- this should follow the pattern of the others
2. A ``requirements.txt`` file that lists the dependencies for the example
3. An ``application.py`` file whose mainline runs a simple version of the example + generates the DAG to
4. A ``statemachine.png`` file that shows the DAG for the example
3. A `notebook.ipynb` file that uses the example in a

The ``notebook.ipynb`` can import stuff from the ``application.py``, or redefine it as an example. If you have something
that does not fit this, or is a prototype but you want to push it in, you can fit in under the ``half-baked`` directory.

---------------
Developer notes
---------------

CLI
---

Burr comes with a `cli` that is both user/developer facing.

**this is required in order to publish, do not do so otherwise**

This will be turned into a `Makefile`, but for now we have a set of commands in `pyproject.toml` that are used to
publish, etc...

To run the just the server for development:

.. code-block:: bash

    $ burr --dev-mode --no-open # will run the server on port 7241

To publish -- this will build the FE + publish the BE to the ``pypi`` prod instance. Note you have to have ``pypi`` credentials to do this:

.. code-block:: bash

    $ burr-admin-publish --prod

To generate the demo data (if you make a change to the schema, ideally forward-compatible):

.. code-block:: bash

    $ burr-admin-generate-demo-data

Not part of the CLI (yet), but running just the UI is simple:

.. code-block:: bash

        $ cd burr/ui
        $ npm run start

Package data
------------

Several static assets are included in the python package so we can run the UI. Namely:

1. The `examples` directory is symlinked from ``burr/examples`` to allow for package-style imports
2. The `build/` directory is symlinked from ``burr/tracking/server`` to allow for static assets referred to by the server to be included in the package. Note that this does not get committed -- this requires use of the CLI above.