Build applications that make decisions (chatbots, agents, simulations, etc...). Monitor, trace, persist, and execute on your own infrastructure.
Python aiburrchatbot-frameworkdagsgenerative-aigraphshacktoberfestllmopsllmsmlopspersistent-data-structurestate-machinestate-managementvisibility
Adds documentation for contributing
elijahbenizzye2b0ba686eb1
diff --git a/README.md b/README.mdindex b6ab2a19..fc286686 100644--- a/README.md+++ b/README.md@@ -43,3 +43,7 @@ pip install burrNext, see the documentation for [getting started](https://studious-spork-n8kznlw.pages.github.io/getting_started/simple-example.html), and follow the example.Then read through some of the concepts and write your own application!++# Contributing++We welcome contributors! To get started on developing, see the [developer-facing docs]([documentation](https://studious-spork-n8kznlw.pages.github.io/contributing))_diff --git a/burr/tracking/server/run.py b/burr/tracking/server/run.pyindex 1be636c9..0876d9cb 100644--- a/burr/tracking/server/run.py+++ b/burr/tracking/server/run.py@@ -14,6 +14,9 @@ app = FastAPI()backend = backend.LocalBackend()+SERVE_STATIC = os.getenv("BURR_SERVE_STATIC", "true").lower() == "true"+print(SERVE_STATIC)+@app.get("/api/v0/projects", response_model=Sequence[schema.Project])async def get_projects(request: Request) -> Sequence[schema.Project]:@@ -55,20 +58,22 @@ async def ready() -> bool:return True-BASE_ASSET_DIRECTORY = str(files("burr").joinpath("tracking/server/build"))--templates = Jinja2Templates(directory=BASE_ASSET_DIRECTORY)-app.mount("/static", StaticFiles(directory=os.path.join(BASE_ASSET_DIRECTORY, "static")), "/static")-# public assets in create react app don't get put under build/static, we need to route them over-app.mount("/public", StaticFiles(directory=BASE_ASSET_DIRECTORY, html=True), "/public")+if SERVE_STATIC:+ BASE_ASSET_DIRECTORY = str(files("burr").joinpath("tracking/server/build"))+ templates = Jinja2Templates(directory=BASE_ASSET_DIRECTORY)+ app.mount(+ "/static", StaticFiles(directory=os.path.join(BASE_ASSET_DIRECTORY, "static")), "/static"+ )+ # public assets in create react app don't get put under build/static, we need to route them over+ app.mount("/public", StaticFiles(directory=BASE_ASSET_DIRECTORY, html=True), "/public")[email protected]("/{rest_of_path:path}")-async def react_app(req: Request, rest_of_path: str):- """Quick trick to server the react app- Thanks to https://github.com/hop-along-polly/fastapi-webapp-react for the example/demo- """- return templates.TemplateResponse("index.html", {"request": req})+ @app.get("/{rest_of_path:path}")+ async def react_app(req: Request, rest_of_path: str):+ """Quick trick to server the react app+ Thanks to https://github.com/hop-along-polly/fastapi-webapp-react for the example/demo+ """+ return templates.TemplateResponse("index.html", {"request": req})if __name__ == "__main__":diff --git a/docs/contributing/architecture.rst b/docs/contributing/architecture.rstnew file mode 100644index 00000000..4af63fec--- /dev/null+++ b/docs/contributing/architecture.rst@@ -0,0 +1,38 @@+============+Architecture+============++Some notes on the design/implementation of Burr:++--------------+Python Package+--------------++Dependencies+------------+A note on dependencies:++- The core Burr library will have zero dependencies. Currently its only dependency in hamilton, but that will be removed in the future.+- Any other extensions (the server, the CLI, etc...) are allowed dependencies -- specify these as install targets in ``pyproject.toml``+- The dependencies/plugins will live alongside the core library, and contain guards to ensure that the right libraries are installed. You can do this with ``burr.integrations.base.require_plugins``++Coding style+------------+We use type hints for function parameters (and in rare cases inline) to aid development but it is not enforced -- use your best judgement++Versioning+----------++We adhere to `sem-var <https://semver.org/>`_ for versioning. We ensure that:++- Every public facing function/class/variable should:+ - have a docstring+ - have type-hints+ - be exposed through the documentation++If it is not exposed through the documentation it is assumed to be private, and thus will+not be subject to sem-var rules.++We currently are not versioning the server or CLI, but are versioning the core library. Note+that it starts at ``0.x``, which means that we are allowed to make a backwards-incompatible change.+We will make every effort not to do so -- and will provide a migration guide/script if we do.diff --git a/docs/contributing/contributing.rst b/docs/contributing/contributing.rstnew file mode 100644index 00000000..c36a1ce7--- /dev/null+++ b/docs/contributing/contributing.rst@@ -0,0 +1,23 @@+============+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 (best way to reach us is via the `slack community <https://join.slack.com/t/hamilton-opensource/shared_invite/zt-1bjs72asx-wcUTgH7q7QX1igiQ5bbdcg>`_)++-----------------------+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 featuresdiff --git a/docs/contributing/index.rst b/docs/contributing/index.rstnew file mode 100644index 00000000..c3361029--- /dev/null+++ b/docs/contributing/index.rst@@ -0,0 +1,18 @@+=========================+Developing / Contributing+=========================++.. _examples:++Instructions to develop/get started with `Burr`! If you don't know where+to start, you can always reach out to us:+- Join our `slack community <https://join.slack.com/t/hamilton-opensource/shared_invite/zt-1bjs72asx-wcUTgH7q7QX1igiQ5bbdcg>`_+- Reach out to us by `email <mailto:[email protected]>`_++.. toctree::+ :maxdepth: 2++ setup+ iterating+ architecture+ contributingdiff --git a/docs/contributing/iterating.rst b/docs/contributing/iterating.rstnew file mode 100644index 00000000..883a8df8--- /dev/null+++ b/docs/contributing/iterating.rst@@ -0,0 +1,77 @@+==========+Developing+==========++-------------+Python Module+-------------++The python module is located in the ``burr/`` directory. Tests are located in the+``tests/`` directory. To run the tests, use the following command:++.. code-block:: bash++ python -m pytest tests/+++---------------+Tracking server+---------------++The tracking server is located inside the python package. To run the server, you can use the utility cli:++.. code-block:: bash++ BURR_SERVE_STATIC=false burr-admin-server --no-open --dev-mode++This will start the server on port 7241. Note that this is just a python wrapper -- this also captures stdout.+We will be fixing this, but ff you want to run it directly (which is best for debugging), you'll want to+run it with uvicorn:++.. code-block:: bash++ BURR_SERVE_STATIC=false uvicorn burr.tracking.server.run:app --port 7241 --reload++We disable serving static files as we want to be able to develop simultaneously with the UI and+npm's reloading capabilities do not work with the static python server.++-----------+Tracking UI+-----------++The tracking UI lives within ``telemetry/ui`` To run the tracking UI, you will need to have npm installed.+Then, you can run the following commands:++.. code-block:: bash++ $ cd telemetry/ui+ $ npm install+ $ npm run start++This will start the UI on port 3000. You can then navigate to ``http://localhost:3000`` to see the UI.+It currently assumes that the tracking server is running on port 7241. The proxy is set up in the+``package.json`` file.++Note that if you want to just develop off the server you'll first have to build the UI and symlink the+``tracking/server/build`` directory to the ``telemetry/ui/build`` directory. We have this structure to+enable easy inclusion of package data in ``pyproject.toml``.++You can do this with the following command:++.. code-block:: bash++ $ burr-admin-build-ui++-------------+Documentation+-------------++The documentation is located in the ``docs/`` directory. To build and serve the documentation,+you can use the following sphinx command:++.. code-block:: bash++ $ sphinx-autobuild -b dirhtml -W -E -T --watch docs/ -a docs /tmp/mydocs++This will start the server on port 8000. You can then navigate to ``http://localhost:8000`` to see the documentation.+Heed any warnings and fix them!diff --git a/docs/contributing/setup.rst b/docs/contributing/setup.rstnew file mode 100644index 00000000..81d4b48f--- /dev/null+++ b/docs/contributing/setup.rst@@ -0,0 +1,55 @@+=====+Setup+=====++These instructions will be assuming use of `pip <https://pip.pypa.io/en/stable/>`_ and `virtualenv <https://virtualenv.pypa.io/>`_.+Replace with your package manager of choice if you prefer.++----------+Clone/fork+----------++To get started, create a fork of Burr on the github UI, and clone it to your local machine.++.. code-block:: bash++ git clone https://github.com/<your_space>/burr.git+++----------+Installing+----------++Next you'll want to ``cd`` into the directory and install+``burr`` in developer mode:++.. code-block:: bash++ cd burr+ pip install -e ".[developer]"++This will install all potential dependencies. Burr will work with ``python >=3.9``.++------------------+Linting/Pre-Commit+------------------++Burr has pre-commit hooks enabled. This comes with the ``developer`` extras.+You can always run the pre-commit hooks manually (on all files). Do this+if it somehow wasn't configured and its in a bad state.++.. code-block:: bash++ pre-commit run --all++For the UI, we leverage husky and lint-staged to run the pre-commit hooks on the client side.+This actually runs pre-commits for the whole repository, so you can run through husky if you want.++You can also run the pre-commit hooks for the UI manually:++.. code-block:: bash++ npm run lint:fix+ npm run format:fix++from within the ``telemetry/ui`` directory.diff --git a/docs/index.rst b/docs/index.rstindex e6feb08d..b7102e2a 100644--- a/docs/index.rst+++ b/docs/index.rst@@ -21,3 +21,10 @@:caption: Reference:reference/index++.. toctree::+ :hidden:+ :maxdepth: 2+ :caption: Contributing:++ contributing/indexdiff --git a/pyproject.toml b/pyproject.tomlindex 26250dcc..06ddfff9 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -82,6 +82,7 @@ developer = ["loguru", # I love loguru TBH, but not for any prod stuff"build","twine",+ "pre-commit",][tool.setuptools]@@ -103,6 +104,7 @@ Repository = "https://github.com/dagworks-inc/burr""Bug Tracker" = "https://github.com/dagworks-inc/burr"[project.scripts]-server = "burr.cli.__main__:cli_run_server"-publish = "burr.cli.__main__:cli_build_and_publish"-build-ui = "burr.cli.__main__:cli_build_ui"+burr = "burr.cli.__main__:cli_run_server"+burr-admin-server = "burr.cli.__main__:cli_run_server"+burr-admin-publish = "burr.cli.__main__:cli_build_and_publish"+burr-admin-build-ui = "burr.cli.__main__:cli_build_ui"