Contribution guide

Setting up the environment

1. Run make install-uv to install uv if not already installed 1. Run make install to install all dependencies and pre-commit hooks

Code contributions

Workflow

1. Fork the Advanced Alchemy repository

2. Clone your fork locally with git

3. Set up the environment

4. Make your changes

5. Run make lint to run linters and formatters. This step is optional and will be executed automatically by git before you make a commit, but you may want to run it manually in order to apply fixes automatically by git before you make a commit, but you may want to run it manually in order to apply fixes

6. Commit your changes to git

7. Push the changes to your fork

8. Open a pull request. Give the pull request a descriptive title indicating what it changes. If it has a corresponding open issue, the issue number should be included in the title as well. For example a pull request that fixes issue bug: Increased stack size making it impossible to find needle #100 could be titled fix(#100): Make needles easier to find by applying fire to haystack

Tip

Pull requests and commits all need to follow the Conventional Commit format

Note

To run the integration tests locally, you will need the ODBC Driver for SQL Server, one option is using unixODBC.

Guidelines for writing code

• All code should be fully typed. This is enforced via mypy.

• All code should be tested. This is enforced via pytest.

• All code should be properly formatted. This is enforced via Ruff.

Writing and running tests

Todo

Write this section

Project documentation

The documentation is located in the /docs directory and is ReST and Sphinx. If you’re unfamiliar with any of those, ReStructuredText primer and Sphinx quickstart are recommended reads.

Running the docs locally

To run or build the docs locally, you need to first install the required dependencies:

make install

Then you can serve the documentation with make docs-serve, or build them with make docs.

Creating a new release

1. Set up your environment

   • Ensure you have the gh CLI installed and logged in to GitHub.

   • Switch to the main branch.

2. Install and update dependencies

   • Run:

     make install   # Install all dependencies
     make upgrade   # Update dependencies to the latest versions
     make docs      # Verify documentation builds
     

3. Bump the version

   • Run:

     make release bump=patch
     

   • Use bump=minor or bump=major if you need to bump the minor or major version instead.

4. Prepare the release

   • Run:

     uv run tools/prepare_release.py -c -i --base v{current_version} {new_version}
     

   • Replace {current_version} with the current version (e.g., 1.2.3).

   • Replace {new_version} with the new version (e.g., 1.2.4).

   • Example: uv run tools/prepare_release.py -c -i --base v1.4.4 1.4.5

5. Run linters and formatters

   • Ensure code style compliance:

     make lint
     

6. Clean up the changelog

   • Open docs/changelog.rst and remove any placeholder comments, such as:

     <!-- By submitting this pull request, you agree to ... -->
     <!-- Please add in issue numbers this pull request will close ... -->
     

7. Commit the release

   • Create a new branch:

     git checkout -b v{new_version}
     

   • Commit the changes:

     git commit -am "chore(release): bump to v{new_version}"
     

8. Open a pull request

   • Push the branch and create a PR into main.

   • Merge once CI checks pass.

9. Verify the release draft

   • Once merged, a draft release will be created under Releases on GitHub.

   • Edit and publish it.

10. Publish to PyPI

    • Approve the Latest Release workflow under Actions to publish the package to PyPI.

Creating a pre-release

Use pre-releases to publish alpha, beta, or release candidate versions. These follow PEP 440 pre-release format (e.g., 1.10.0a1, 1.10.0b1, 1.10.0rc1).

1. Bump to a pre-release version

   make pre-release version=1.10.0a1    # First alpha
   make pre-release version=1.10.0a2    # Second alpha
   make pre-release version=1.10.0b1    # First beta
   make pre-release version=1.10.0rc1   # First release candidate
   

2. Commit and push

   git add -A && git commit -m "chore(release): bump to v1.10.0a1"
   git push origin HEAD
   

3. Create a GitHub pre-release

   gh release create v1.10.0a1 --prerelease --title "v1.10.0a1"
   

4. PyPI behavior

   PyPI automatically marks PEP 440 pre-release versions:

   • Users won’t get pre-releases via pip install advanced-alchemy

   • Users can opt-in via pip install --pre advanced-alchemy

   • Or pin explicitly: pip install advanced-alchemy==1.10.0a1

Graduating from pre-release to stable

From the last release candidate, bump the pre part to move past rc to stable:

make release bump=pre    # e.g. 1.10.0rc1 → 1.10.0

Or skip to the next stable version directly:

make release bump=patch  # From any version → next patch
make release bump=minor  # From any version → next minor

Then follow the standard Creating a new release steps above.