Contributing¶

Thank you for your interest in contributing to project-guide! This document provides guidelines for contributing to the project.

Code of Conduct¶

Be respectful and constructive in all interactions with the project and community.

How to Contribute¶

Reporting Issues¶

If you find a bug or have a feature request:

Check if the issue already exists in GitHub Issues
If not, create a new issue with:
Clear description of the problem or feature
Steps to reproduce (for bugs)
Expected vs. actual behavior
Your environment (OS, Python version, package version)

Suggesting Improvements¶

For template improvements or new features:

Open a GitHub Discussion
Describe your suggestion and use case
Discuss with maintainers before implementing

Submitting Pull Requests¶

Fork the repository

git clone https://github.com/your-username/project-guide.git
cd project-guide

Create a branch

git switch -c feature/your-feature-name

Set up development environment

pyve run pip install -e .                       # main env: editable install
pyve testenv init                               # create the dev testenv
pyve testenv install -r requirements-dev.txt    # pytest, ruff, mypy

Make your changes
Follow existing code style
Add tests for new functionality
Update documentation as needed
Run tests
```
pyve test
```

Run linters

pyve testenv run ruff check project_guide tests
pyve testenv run mypy project_guide

Commit your changes

git add .
git commit -m "Add feature: description"

Push to your fork

git push origin feature/your-feature-name

Create a Pull Request
Go to the original repository
Click "New Pull Request"
Select your branch
Describe your changes

Development Guidelines¶

Code Style¶

Follow PEP 8 style guidelines
Use type hints for function signatures
Keep functions focused and small
Write descriptive variable names

Testing¶

Write tests for new features
Maintain or improve test coverage (minimum 85%, currently 90%)
Run tests with pyve test (pytest lives in the dev testenv)
Test edge cases and error conditions
596 tests across 12 test files

Documentation¶

Update docstrings for modified functions
Update user documentation for user-facing changes
Update CHANGELOG.md with your changes
Keep documentation clear and concise

Template Improvements¶

When improving templates:

Test rendering: Verify templates render correctly with project-guide init and mode selection
Be specific: Provide concrete steps, not vague instructions
Include examples: Show what good output looks like
Consider edge cases: Handle common variations
Maintain consistency: Follow existing template structure

Project Structure¶

project-guide/
├── project_guide/              # Main package
│   ├── cli.py                  # CLI commands
│   ├── config.py               # Configuration handling
│   ├── metadata.py             # Metadata loading and validation
│   ├── render.py               # Jinja2 template rendering
│   ├── sync.py                 # File synchronization
│   ├── exceptions.py           # Custom exception classes
│   ├── version.py              # Version information
│   └── templates/              # Bundled templates
│       └── project-guide/      # Project guide templates
│           ├── .metadata.yml   # Mode and artifact definitions
│           ├── README.md       # Template README
│           ├── developer/      # Developer guide templates
│           └── templates/      # Jinja2 templates
│               ├── modes/      # Mode templates (*.md)
│               ├── artifacts/  # Artifact templates (*.md)
│               └── go.md       # Go template
├── tests/                      # Test suite (596 tests, 90% coverage)
│   ├── test_cli.py             # CLI command tests (~200)
│   ├── test_render.py          # Render tests, incl. per-mode (~170)
│   ├── test_actions.py         # Deterministic actions / archive (~53)
│   ├── test_runtime.py         # Runtime helpers (~52)
│   ├── test_stories.py         # Story parsing / git-push messages (~35)
│   ├── test_sync.py            # Sync logic tests (~25)
│   ├── test_config.py          # Configuration tests (~19)
│   ├── test_metadata.py        # Metadata tests (~18)
│   ├── test_archive_stories_mode.py  # archive_stories mode (~8)
│   ├── test_integration.py     # Integration tests (~6)
│   ├── test_purge.py           # Purge command tests (~5)
│   └── test_cross_repo_contract.py   # Pyve cross-repo contracts (~3)
├── docs/                       # Documentation
│   └── site/                   # MkDocs documentation
└── pyproject.toml              # Package configuration

Dependencies¶

Runtime:

click
jinja2
pyyaml
packaging

Development:

ruff
mypy
pytest-cov

Testing Locally¶

Run All Tests¶

pyve test

Run Specific Tests¶

pyve test tests/test_cli.py
pyve test tests/test_cli.py::test_init_in_empty_directory

Check Coverage¶

pyve test --cov=project_guide --cov-report=html
open htmlcov/index.html

Run Linters¶

# Check code style
pyve testenv run ruff check project_guide tests

# Type checking
pyve testenv run mypy project_guide

# Format code
pyve testenv run ruff format project_guide tests

Building Documentation¶

Build MkDocs Site¶

mkdocs build

Serve Locally¶

mkdocs serve
# Open http://127.0.0.1:8000

Release Process¶

(For maintainers)

Update version in project_guide/version.py
Update CHANGELOG.md
Commit changes
Create and push tag
GitHub Actions will build and publish to PyPI

Getting Help¶

GitHub Discussions - Ask questions
GitHub Issues - Report bugs
Documentation - Read the docs

License¶

By contributing, you agree that your contributions will be licensed under the Apache-2.0 License.