Contribute

Please contribute to the ASSET Lab Resource Adequacy Package! The guidelines below are intended for contributors with a wide range of open-source development experience.

Setup

1. Install Python 3

2. Install Git

3. Create a GitHub Account

4. Setup GitHub Authentication. Either:

   1. Setup GitHub SSH Keys

   2. Setup Personal Access Token

5. Fork assetra on GitHub.

   • This creates your own version of the assetra repository. You will make changes to your fork and submit them for review to be added to the main assetra repository.

6. Clone your Fork Locally.

   1. Navitage to the directory where you would like your clone to live.:

      git clone https://github.com/<your username>/assetra.git
      

7. Setup Poetry

   • Poetry is used to (1) manage virtual environments used to test development code, (2) maintain the pyproject.toml file which defines package dependencies to be installed with assetra by end-users, and (3) automate the process of building the assetra package and publishing to pypi. When a contributor updates their environment (i.e. they install new or upgrade existing dependencies that need to be shipped with assetra), they should commit their modifications to the pyproject.toml and poetry.lock files. Other contributors should then run poetry install to remain in sync.

   1. Install pipx:

      python3 -m pip install pipx
      

   2. Install Poetry:

      pipx install poetry
      

   3. Create a Virtual Environment:

      python3 -m venv env
      

   4. Activate the Virtual Environment:

      source env/bin/activate # linux
      env/Scripts/activate # windows
      

   5. Install Dependencies:

      poetry install
      

   6. Test Installation:

      poetry run python -m unittest
      

Contributor Workflow

1. Identify an existing issue or open a new one in GitHub.

2. Create a branch in your fork to work on your contributions.

3. Modify files. Follow these guidelines when contributing:

   • For every function added or modified:

     1. Add at least one unit test.

   1. For every new EnergyUnit added:

   usage.rst

   1. Add an example in the examples folder. Include all data needed to run a working example, but be mindful of the file sizes.

   2. Update docs/reference.rst to help others understand what you are modeling and what assumptions you make in your implementation.

4. Run all unit tests. Ensure they run successfully.

   poetry run python -m unittest

5. Commit changes:

   git status # show files modified
   git add <files> # space-separated list of files modified to be committed.
   git commit # will open a text editor for you to describe your changes.
   

6. Push local changes back to your fork on GitHub:

   git push
   

7. Open a pull request to ijbd/assetra to submit your modifications for review.

Reviewer Workflow

1. Review code modifications.

2. Review new/modified unit tests.

3. Review new/modified examples.

4. Run all unit tests.

5. Run new/modified examples.

6. Request changes, if needed.

7. Confirm pull request will close relevant issues.

8. Accept the pull request.

9. Release the new code:

   1. Bump the code version in assetra/__init__.py and pyproject.toml. Commit these changes.

   2. Build the package:

      poetry build
      

   3. Publish package to pypi (requires pypi token):

      poetry publish --build