|
| 1 | +# GUIDELINES |
| 2 | + |
| 3 | +These guidelines are recommended for anyone creating a repository using this template for building reference implementations. |
| 4 | + |
| 5 | +## Repository Name |
| 6 | + |
| 7 | +Choose a repository name that reflects the main topic of your reference implementations. Avoid generic terms like 'workshop', 'bootcamp', 'reference', or 'implementations'. Instead, use a concise topic name that best describes the content. |
| 8 | + |
| 9 | +**Example:** Use `retrieval-augmented-generation` if your repository contains reference implementations for RAG concepts. Select a single, descriptive topic name for the project. |
| 10 | + |
| 11 | +> **Note:** If you cannot use the recommended naming convention initially, you may start with a different name and update it later. |
| 12 | +
|
| 13 | +## Environment Variables |
| 14 | + |
| 15 | +Manage environment variables using a `.env` file and access them in your code with `os.getenv("ENV_VARIABLE", "default-value")`. List all environment-specific variables in a `.env.example` file with placeholder values for easy reference and onboarding. |
| 16 | + |
| 17 | +## Utility Packages |
| 18 | + |
| 19 | +Place all common methods and classes used across implementations in a dedicated module at the repository root. Each package should have its own `pyproject.toml` specifying its details and dependencies. For example, this repository includes the `aieng-topic-impl` package. |
| 20 | + |
| 21 | +If your repository contains multiple packages, link each one in the main `pyproject.toml` as shown below to ensure they are built and linked for local development: |
| 22 | + |
| 23 | +```toml |
| 24 | +[tool.uv.workspace] |
| 25 | +members = [ |
| 26 | + "aieng-topic-impl", |
| 27 | +] |
| 28 | + |
| 29 | +[tool.uv.sources] |
| 30 | +aieng-topic-impl = { workspace = true } |
| 31 | +``` |
| 32 | + |
| 33 | +When testing packages, use pre-release versions (e.g., v0.1.0a1, v0.1.0a2, v0.1.0b1). After testing, update to a release version (e.g., v1.0.0) before publishing. Follow the [official versioning scheme](https://packaging.python.org/en/latest/discussions/versioning/). |
| 34 | + |
| 35 | +## Google Colab Integration (For Notebooks Only) |
| 36 | + |
| 37 | +Ensure Jupyter Notebooks are runnable on Google Colab. This may require installing your locally linked package and resolving dependency conflicts in the Colab environment. |
| 38 | + |
| 39 | +Add the following Markdown cell at the top of your notebook to enable opening it in Colab: |
| 40 | + |
| 41 | +```markdown |
| 42 | +[](https://colab.research.google.com/github/VectorInstitute/<REPO_NAME>/blob/main/<PATH_TO_NOTEBOOK>) |
| 43 | +``` |
| 44 | + |
| 45 | +Include a Python cell like the one below at the beginning of your notebook to customize it for Colab: |
| 46 | + |
| 47 | +```python |
| 48 | +import os |
| 49 | + |
| 50 | +if "COLAB_RELEASE_TAG" in os.environ: |
| 51 | + # Running in Google Colab |
| 52 | + # Install required dependencies |
| 53 | + !pip3 install numpy==1.26.4 torchvision==0.16.2 aieng-topic-impl |
| 54 | + # Uninstall conflicting dependencies |
| 55 | + !pip3 uninstall --yes torchao torchaudio torchdata torchsummary torchtune |
| 56 | +``` |
| 57 | + |
| 58 | +## Dockerization |
| 59 | + |
| 60 | +Dockerize your project to ensure portability and consistency across platforms. This also facilitates deployment on the AI Engineering Platform used in bootcamps and workshops. |
| 61 | + |
| 62 | +- Update the provided `Dockerfile` to suit your project’s needs. |
| 63 | +- Modify `scripts/start.sh` to reflect your setup steps. This script will run at container startup. |
| 64 | +- Update the `README.md` with instructions to build and start the Docker container. |
| 65 | + |
| 66 | +## GitHub Actions |
| 67 | + |
| 68 | +### Publish |
| 69 | + |
| 70 | +Use this GitHub Actions workflow to publish packages. Create a PyPI token and set the `PYPI_API_TOKEN` secret in your repository settings. To trigger the publish workflow, create a GitHub Release and push a new tag (e.g., `v0.1.0`). |
| 71 | + |
| 72 | +After publishing, test the package by installing it in a new virtual environment and performing a sanity check. |
0 commit comments