Contributing Guidelines

Getting Started

To contribute to GatorGrade, you must have Python 3.7 or later and Poetry installed.

To set up a development environment for GatorGrade, first clone the GatorGrade repository.

git clone [email protected]:GatorEducator/gatorgrade.git

Then, in your copy of GatorGrade, run poetry install. This will install all of GatorGrade's runtime and development dependencies. Now, you can begin to contribute to the GatorGrade project following the guidelines below.

Contributing Changes

GitHub Flow

GatorGrade is maintained using the GitHub Flow workflow. This means that before making any changes to your copy of GatorGrade, you should create a new branch off of the main branch. The name of the branch should be a short, descriptive name that describes the changes you plan on making in the branch. For example, if you are planning to update the README.md, you might name your branch update-readme. Notice that the branch name should be all lowercase and have words separated by hyphens.

Testing Changes

Running GatorGrade Locally

As you make changes, you will want to see how they affect the output of GatorGrade. To do this, in the branch that contains your changes, run:

poetry build

This will build an archive (i.e. a release artifact) of GatorGrade that contains your changes. To use this archive, you can install it with pipx:

pipx install dist/gatorgrade-<archive-version>.whl

Then, you can run the gatorgrade command in any assignment repository to view the output of GatorGrade with your changes.

If you have already done this, have made additional changes, and would like to try out your most recent changes, we recommend that you first uninstall GatorGrade with pipx:

pipx uninstall gatorgrade

Then, you can proceed with building and installing a new GatorGrade archive.

Running the Test Suite

You should also test that your changes have not caused any regressions in the GatorGrade system. You can do this by running:

poetry run task test

This will run the test task defined in the pyproject.toml, which will execute all of the tests. You can be confident that your changes have not caused any regressions if all tests pass.

Additionally, you should lint your changes to make sure they follow the stylistic rules of the GatorGrade project. You can do this by running:

poetry run task lint

This will run the lint task, which executes various linters such as pylint, that ensure that the style of your changes matches the rest of GatorGrade. Any linting errors that appear should be addressed.

Committing Changes

As you make and test changes, you should be making small, focused, and targeted commits. Additionally, commit messages should follow these guidelines:

• Should be 50 characters or less (soft limit - exceptions include co-author or function names for example)
• Should be in the imperative mood
• Should be void of all grammatical and spelling mistakes

Submitting Changes For Review

Once you have finished making and committing your changes to your branch, you should create a pull request so that others can review your changes. Before creating a pull request, make sure that the last commit in your branch produced a passing build in GitHub Actions. When you create a pull request, please make sure to fill out all portions of the template.