Contributing Guide

Thank you for your interest in contributing to Medieval Deck! This guide provides all the information you need to get started with development.

Development Environment Setup

  1. Fork and Clone: Fork the repository on GitHub, then clone your fork to your local machine.
  2. Install Dependencies: Follow the instructions in the Installation Guide to set up your virtual environment and install all required packages.

Running Tests

The project uses a suite of tests located in the /tests directory to verify functionality for each sprint. It is crucial to run these tests to ensure your changes do not break existing features.

To run the tests for a specific sprint, execute the corresponding test file. For example, to run the Sprint 4 tests:

python tests/test_sprint4.py

To run all tests, you can use a simple loop (on Linux/macOS):

for test_file in tests/test_*.py; do python "$test_file"; done

Before submitting a pull request, please ensure that all tests pass.

Sprint-Based Workflow

The project follows a structured, 15-sprint development cycle outlined in the Development Roadmap. When contributing, please ensure your work aligns with the goals of the current or upcoming sprints.

  • Focus on Modularity: Do not mix logic from different systems (e.g., UI and AI generation) in the same module. Adhere to the established Architecture.
  • Preserve File Structure: Do not move or rename files without a strong architectural reason.
  • Do Not Modify AI Logic Blindly: The files in /gen_assets contain carefully tuned logic for the AI pipeline. Be cautious when making changes here.

Coding Conventions

  • Docstrings: All functions and classes should have clear, descriptive docstrings explaining their purpose, arguments, and return values.
  • Configuration: All global constants should be placed in config.py. Avoid hard-coded values in game logic files.
  • Asset Management: Do not commit large generated asset files to the repository. The .gitignore file should be configured to ignore the contents of assets/ and gen_assets/ subdirectories where images are cached. Mock assets for testing are acceptable.

Submitting Changes

  1. Create a new branch for your feature or bug fix. 
    git checkout -b feature/my-new-feature
  2. Make your changes and commit them with a clear, descriptive message. 
    git add .
git commit -m "feat: Implement a new card effect system"
  3. Push your branch to your fork. 
    git push origin feature/my-new-feature
  4. Open a Pull Request from your fork to the main Noquela/MedievalDeck repository. In the description, explain the changes you made and reference any relevant issues.