Skip to content

armgit / burr

Public Imported from GitHub
0

Build applications that make decisions (chatbots, agents, simulations, etc...). Monitor, trace, persist, and execute on your own infrastructure.

Adds documentation for contributing

elijahbenizzye2b0ba686eb1
diff --git a/README.md b/README.md
index b6ab2a19..fc286686 100644
--- a/README.md
+++ b/README.md
@@ -43,3 +43,7 @@ pip install burr
Next, 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.py
index 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.rst
new file mode 100644
index 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.rst
new file mode 100644
index 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 features
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
new file mode 100644
index 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
+ contributing
diff --git a/docs/contributing/iterating.rst b/docs/contributing/iterating.rst
new file mode 100644
index 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.rst
new file mode 100644
index 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.rst
index 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/index
diff --git a/pyproject.toml b/pyproject.toml
index 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"