From cbf7c62524cfbafc98bfe66e1d43191028c1dba9 Mon Sep 17 00:00:00 2001 From: Ben Browning Date: Thu, 9 Jan 2025 16:08:27 -0500 Subject: [PATCH] Add a CONTRIBUTING.md with basic dev setup instructions This isn't exhaustive, but should give a basic starting point for anyone wanting to work on SDG locally. Signed-off-by: Ben Browning --- CONTRIBUTING.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..d364b186 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,107 @@ +# Local Development Setup + +## Fork and clone the SDG repository locally + +Follow GitHub's documentation for [forking a +repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) +to learn how to fork and clone the +[instructlab/sdg](https://github.com/instructlab/sdg) repository to +your local machine. If you don't want to submit pull requests to SDG, +you can skip the forking step and directly clone the instructlab/sdg +repository. If you intend to submit a pull request, it's best to fork +first. + +The subsequent instructions assume you have cloned SDG to a local +directory and are executing these commands from within that +directory. For example, it assumes you've done something like this: + +```shell +git clone git@github.com:instructlab/sdg.git +cd sdg +``` + +## Setup a Python virtual environment and install InstructLab + +```shell +python3 -m venv --upgrade-deps venv +. venv/bin/activate +pip install git+https://github.com/instructlab/instructlab@main +``` + +At this point, you have InstructLab installed and a working `ilab` +CLI. However, it is using a released version of SDG and not your +locally cloned one. + +## Overwrite SDG with your locally cloned one + +Now let's override the SDG version installed with our locally cloned +one. We'll use the `-e` flag to `pip install` so that we can edit the +SDG files and changes immediately take effect, without having to run +`pip install` again after each edit. We also install the development +requirements, necessary to run tests. + +```shell +pip install -e . +pip install -r requirements-dev.txt +``` + +This may give a warning from pip about its dependency resolver and +instructlab-sdg versions. You can ignore that, as we are explicitly +using an unreleased local version of instructlab-sdg here. + +## Test SDG + +At this point, you should be able to run SDG tests locally as a sanity +check to ensure your local development environment is setup. The first +time you run them may take a bit as `tox` installs the necessary +development requirements. Subsequent runs will be faster. + +### Unit Tests + +These are relatively fast to run, with each testing a small section of +the SDG code. + +```shell +tox -e py3-unit +``` + +### Functional Tests + +These take a bit longer to run, and test larger functional areas of +the SDG code. + +```shell +tox -e py3-functional +``` + +### Manual Testing / usage + +You can also invoke the `ilab` CLI or use the SDG Python APIs directly +to test things locally. Details on how to use the `ilab` CLI are +maintained in the [upstream InstructLab +documentation](https://github.com/instructlab/instructlab). + +## Running code formatting and linting checks locally + +To run the same checks locally that our CI system uses to evaluate PRs +for linting errors, unused imports, code style, etc: + +```shell +tox -e ruff -- check +tox -e lint +tox -e mypy +tox -e validate-pipelines +``` + +Also run the unit and functional tests, mentioned above, before +opening a pull request to ensure the tests pass with your changes. + +## Proposing changes to the project + +We follow a standard GitHub [fork and pull +model](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models#fork-and-pull-model) +to allow anyone to fork our repository and propose changes via a pull +request. If you're unfamiliar with how to submit a pull request, the +GitHub documentation on [Collaborating with pull +requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests) +is a good guide to follow.