Contributing to UQLM#

Welcome and thank you for considering contributing to UQLM!

It takes a lot of time and effort to use software much less build upon it, so we deeply appreciate your desire to help make this project thrive.

Table of Contents#

  1. How to Contribute

  2. Development Setup

  3. Style Guides

  4. License

How to Contribute#

Reporting Bugs#

If you find a bug, please report it by opening an issue on GitHub. Include as much detail as possible: * Steps to reproduce the bug. * Expected and actual behavior. * Screenshots if applicable. * Any other information that might help us understand the problem.

Suggesting Enhancements#

We welcome suggestions for new features or improvements. To suggest an enhancement, please open an issue on GitHub and include:

  • A clear description of the suggested enhancement.

  • Why you believe this enhancement would be useful.

  • Any relevant examples or mockups.

Pull Requests#

  1. Fork the repository.

  2. Create a new branch (git checkout -b feature/your-feature-name).

  3. Make your changes.

  4. Commit your changes (git commit -m 'Add some feature'`).

  5. Push to the branch (git push origin feature/your-feature-name).

  6. Open a pull request.

Please ensure your pull request adheres to the following guidelines:

  • Follow the project’s code style.

  • Include tests for any new features or bug fixes.

Development Setup#

  1. Clone the repository: git clone https://github.aetna.com/analytics-org/uqlm.git

  2. Navigate to the project directory: cd uqlm

  3. Create and activate a virtual environment (using venv or conda)

  4. Install poetry (if you don’t already have it): pip install poetry

  5. Install uqlm with dev dependencies: poetry install --with dev

  6. Install our pre-commit hooks to ensure code style compliance: pre-commit install

  7. Run tests to ensure everything is working: pre-commit run --all-files`

You’re ready to develop!

For documentation contributions

Our documentation lives on the gh-pages branch and is hosted via GitHub Pages.

There are two relevant directories:

  • docs_src - where source documentation files are located

  • docs - where the built documentation is located that is served by GitHub Pages

To build the documentation locally:

  1. Create a virtual environment with your favorite tool(ex. conda, virtualenv, uv, and etc.)

  2. Checkout the gh-pages branch and create new branch from it

  3. Navigate to the docs_src/latest directory

  • If this is version upgrade:

    1. Copy latest contents to docs_src/{version_number} folder update the version in conf.py file

    2. Copy latest contents from docs/ to docs/{version_number} folder

    3. Update the versions in docs_src/latest/index.rst file and docs_src/versions.json

  1. cd uqlm

  2. pip install -e . # installs current uqlm repo as package to environment

  3. cd docs_src/latest

  4. brew install pandoc # to use nbsphinx extension

  5. make install # installs sphinx related python packages

  6. make github # builds docs html

  7. make local # locally test doc site

Style Guides#

Code Style#

  • We use Ruff to lint and format our files.

  • Our pre-commit hook will run Ruff linting and formatting when you commit.

  • You can manually run Ruff at any time Ruff usage.

Please ensure your code is properly formatted and linted before committing.

License#

Before contributing to this CVS Health sponsored project, you will need to sign the associated Contributor License Agreement (CLA).

Thanks again for using and supporting uqlm!