Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
355 lines (254 loc) · 13.1 KB

CONTRIBUTING.md

File metadata and controls

355 lines (254 loc) · 13.1 KB

🤝 Contributing to auth

Thank you for your interest in contributing to auth! This document provides guidelines and instructions for setting up your development environment and contributing to the project.

📚 Table of Contents

🚧 Getting Started

We encourage developers to work on their own forks of the repository. This allows you to work on features or fixes without affecting the main codebase until your changes are ready to be merged.

🌐 Deployment Environment

We maintain two deployment environments:

🔄 Development Workflow

The standard workflow for contributing is as follows:

  1. Fork the repository on GitHub and clone it to your local machine.
  2. Create a new branch for your feature or bug fix.
  3. Make your changes and commit them with clear, descriptive messages.
  4. Push your branch to your fork on GitHub.
  5. Create a Pull Request (PR) against the repository's dev branch (not main).
  6. Wait for review and feedback from the maintainers, address any comments or suggestions.
  7. Once approved, your changes will be merged into the dev branch and deployed to staging for testing.
  8. After all pre-commit checks pass, deployment to staging is triggered automatically.
  9. Production deployment is performed manually by authorized maintainers after successful staging validation.

Warning

Please note that you will not be able to push directly to either the dev or main branches of the repository. All PRs must be raised from a feature branch of your forked repository and target the dev branch. Direct PRs to main will be closed.

🛠️ Development Environment Setup

This section provides instructions for setting up your development environment to work on the project. We recommend using a package manager like uv to manage dependencies and avoid conflicts with other projects.

Prerequisites

  • Python 3.11 or higher
  • Git
  • Docker

Setting Up Your Environment

  1. Create and activate a virtual environment:

    uv venv --python 3.11
source .venv/bin/activate

  2. Install dependencies:

    uv sync --all-extras

Set Up Environment Variables

  1. Copy the example environment file to create your own:

    cp .env.example .env

  2. Configure your test credentials: Open the .env file and replace all <YOUR_..._HERE> placeholders with your actual test user details. Each variable has been documented in the .env.example file for clarity.

Pre-commit Hooks

We use pre-commit hooks to ensure code quality and consistency. These will automatically run checks before you commit your code. Install the pre-commit hooks by running:

pre-commit install

🧰 Running the Application

You can run the application using the same instructions as in the README.md file. To ensure parity with production, we recommend testing the app both locally and inside Docker. See the README.md for Docker instructions.

🧪 Testing and Code Quality

We enforce code quality and correctness using pre-commit, which runs formatters, linters, upgrade checks, and the test suite automatically before every commit.

Pre-commit Hooks

The following checks are enforced:

  • ✅ ruff for linting and formatting (with auto-fix)
  • ✅ blacken-docs to format code blocks inside Markdown files
  • ✅ pyupgrade to upgrade syntax to Python 3.9+
  • ✅ end-of-file-fixer, trailing-whitespace, check-yaml, check-toml, requirements-txt-fixer for formatting
  • ✅ name-tests-test to enforce test naming conventions
  • ✅ debug-statements to prevent committed print() or pdb
  • ✅ A local pytest hook that runs the full test suite

Warning

You will not be able to commit code that fails these checks.

Linting & Formatting

All linting and formatting is handled by ruff. Run the following command to check all files:

pre-commit run --all-files

🧪 Running Tests

We use pytest, and a pre-commit hook ensures tests are run automatically before every commit.

To run tests manually:

uv run pytest

To check coverage:

uv run pytest --cov

Note

The pre-commit hook runs python scripts/run_tests.py, which uses the same underlying pytest runner.

Writing Tests

  • Write tests for all new features and bug fixes
  • Place them in the tests/ directory
  • Name your test files and functions with the test_ prefix (required by pytest and validated by pre-commit)
  • Keep test cases small, meaningful, and well-named

🚀 Submitting Changes

🔀 Create a Branch

Start by creating a new branch for your work:

git checkout -b your-feature-name

Replace your-feature-name with a descriptive name related to the change (e.g., fix-token-expiry-bug or docs-update-readme).

✏️ Make and Commit Changes

After making your changes, commit them with a clear, conventional message:

git add .
git commit -m "fix: resolve token expiry issue"

Use Conventional Commits to keep commit history consistent:

Type Use for…
feat: New features
fix: Bug fixes
docs: Documentation changes
style: Formatting (no code change)
refactor: Code changes that aren't bug fixes or features
test: Adding or modifying tests
chore: Maintenance (build, deps, etc.)

📤 Push and Open a Pull Request

  1. Push your branch to your fork:

    git push origin your-feature-name

  2. Open a Pull Request (PR) on GitHub targeting the dev branch.

  3. In your PR:

    • Use a clear and descriptive title
    • Include a summary of your changes
    • Link any related issues using Closes #issue-number
    • Add screenshots, terminal output, or examples if relevant

After your PR is merged into dev, all pre-commit checks will run automatically. If they pass, deployment to staging is triggered. The maintainers will review your PR, provide feedback, and may request changes. Once approved, your PR will be merged into the dev branch and deployed to staging for testing. After successful validation, changes will be promoted to production which is manually trigerred by authorized maintainers.

❓ Need Help?

If you get stuck or have questions:

  1. Check the README.md for setup and usage info.
  2. Review open issues or pull requests to see if someone else encountered the same problem.
  3. Reach out to the maintainers on PESU Discord.
    • Use the #pesu-auth channel for questions related to this repository.
    • Search for existing discussions before posting.
  4. Open a new issue if you're facing something new or need clarification.

🔐 Security

If you discover a security vulnerability, please do not open a public issue.

Instead, report it privately by contacting the maintainers. We take all security concerns seriously and will respond promptly.

✨ Code Style Guide

To keep the codebase clean and maintainable, please follow these conventions:

✅ General Guidelines

  • Write clean, readable code
  • Use meaningful variable and function names
  • Avoid large functions; keep logic modular and composable
  • Use Python 3.11+ syntax when appropriate (e.g., match, | union types)
  • Keep imports sorted and remove unused ones (handled automatically via ruff)

📝 Docstrings & Comments

  • Add docstrings to all public functions, classes, and modules
  • Use Google-style docstrings (or consistent alternatives)
  • Write comments when logic is non-obvious and avoid restating the code

Example:

def send_otp(email: str) -> bool:
    """
    Sends a one-time password to the given email.

    Args:
        email (str): User's email address

    Returns:
        bool: True if the OTP was sent successfully, False otherwise
    """

🏷️ GitHub Labels

We use GitHub labels to categorize and prioritize issues and pull requests. Here’s a guide to help you understand what each label means:

🧑‍💻 Contribution Level

Label Description
good first issue 🟢 Simple, well-scoped tasks good for first-time contributors
help wanted 🟡 Maintainers are actively seeking help on this issue

🐞 Bug & Error Handling

Label Description
bug 🔴 A defect or unexpected behavior in the application
invalid 🚫 The issue/PR is not valid or based on a misunderstanding
wontfix ❌ The issue is acknowledged but will not be fixed
duplicate 📑 This issue or PR duplicates an existing one

✨ Feature Development

Label Description
enhancement 🟢 A request or proposal for improvement or new feature
feature 🌟 Work related to adding a new capability
question ❓ Request for clarification or discussion

📚 Documentation

Label Description
documentation 📘 Updates to README, docstrings, or inline comments

🧪 Testing & CI/CD

Label Description
tests and ci/cd 🧪 Changes or issues related to testing or continuous integration

🔒 Authentication & Core

Label Description
authentication 🔐 Login, CSRF, token handling, error flows
pesuacademy 🎓 PESUAcademy client, authentication, and scraping logic
student profile 🧑‍🎓 HTML parsing & profile field extraction logic

🧠 Meta / Organization

Label Description
api ⚙️ Core FastAPI application and route handlers
discussion 🗣️ Open-ended conversation about project direction

Note

When opening or triaging issues and PRs, feel free to suggest an appropriate label. Maintainers will review and apply them accordingly.

🧩 Feature Suggestions

If you want to propose a new feature:

  1. Check if it already exists in issues
  2. Open a new issue using the "Feature Request" template if available
  3. Clearly explain the use case, proposed solution, and any relevant context

📄 License

By contributing to this repository, you agree that your contributions will be licensed under the MIT License. See LICENSE for full license text.