- Notifications
You must be signed in to change notification settings - Fork261
feat: add Copilot instructions for repository#1354
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Draft
Copilot wants to merge2 commits intomasterChoose a base branch
base:master
Could not load branches
Branch not found:{{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline, and old review comments may become outdated.
Uh oh!
There was an error while loading.Please reload this page.
Draft
Changes fromall commits
Commits
Show all changes
2 commits Select commitHold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Jump to
Jump to file
Failed to load files.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Diff view
Diff view
There are no files selected for viewing
276 changes: 276 additions & 0 deletions.github/copilot-instructions.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,276 @@ | ||
| # Copilot Instructions for python-semantic-release | ||
| ## Project Overview | ||
| Python Semantic Release is a tool for automating semantic versioning and package releases for Python projects. It analyzes commit messages following the Conventional Commits specification to determine version bumps, generate changelogs, and publish releases. | ||
| **Key Components:** | ||
| - **CLI**: Command-line interface for version management, changelog generation, and publishing | ||
| - **Commit Parsers**: Parse commit messages to determine version bumps (Angular, Emoji, Scipy, Tag formats) | ||
| - **HVCS Integration**: Integrations with GitHub, GitLab, Gitea, and Bitbucket for releasing | ||
| - **Version Management**: Semantic versioning logic and version calculation | ||
| - **Changelog Generation**: Automated changelog creation using Jinja2 templates | ||
| ## Development Setup | ||
| ### Installation | ||
| ```bash | ||
| # Install with development dependencies | ||
| pip install -e .[dev,mypy,test] | ||
| # For documentation development | ||
| pip install -e .[docs] | ||
| ``` | ||
| ### Running the Application | ||
| ```bash | ||
| # Run the CLI | ||
| semantic-release --help | ||
| # Common commands | ||
| semantic-release version | ||
| semantic-release changelog | ||
| semantic-release publish | ||
| ``` | ||
| ## Code Style and Quality | ||
| ### Linting and Formatting | ||
| - **Ruff**: Primary linter and formatter (replaces Black, isort, flake8) | ||
| ```bash | ||
| ruff check . | ||
| ruff format . | ||
| ``` | ||
| - **Type Checking**: Use mypy for type checking | ||
| ```bash | ||
| mypy . | ||
| ``` | ||
| ### Code Style Guidelines | ||
| 1. **Type Hints**: All functions must have complete type hints (enforced by mypy) | ||
| 2. **Docstrings**: Use Google-style docstrings (though currently many are missing - this is being addressed) | ||
| 3. **Line Length**: 88 characters (enforced by Ruff) | ||
| 4. **Import Style**: | ||
| - Absolute imports only (no relative imports) | ||
| - Use `from __future__ import annotations` for forward references | ||
| - Combine imports from same module with `as` aliases | ||
| 5. **String Quotes**: Use double quotes for strings | ||
| 6. **Error Handling**: Create specific exception classes inheriting from `SemanticReleaseBaseError` | ||
| ### Common Patterns | ||
| - Configuration uses Pydantic models (v2) for validation | ||
| - CLI uses Click framework with click-option-group for organization | ||
| - Git operations use GitPython library | ||
| - Templating uses Jinja2 for changelogs and release notes | ||
| ## Testing | ||
| ### Test Structure | ||
| - **Unit Tests**: `tests/unit/` - Fast, isolated tests | ||
| - **E2E Tests**: `tests/e2e/` - End-to-end integration tests with real git repos | ||
| - **Fixtures**: `tests/fixtures/` - Reusable test data and fixtures | ||
| ### Running Tests | ||
| ```bash | ||
| # Run all tests for current Python version | ||
| pytest | ||
| # Run with full verbosity | ||
| pytest -vv | ||
| # Run only unit tests | ||
| pytest -m unit | ||
| # Run only e2e tests | ||
| pytest -m e2e | ||
| # Run comprehensive test suite (all variations) | ||
| pytest -vv --comprehensive | ||
| # Run tests across all Python versions | ||
| tox | ||
| ``` | ||
| ### Testing Guidelines | ||
| 1. **Test Organization**: Group tests by module structure mirroring `src/` | ||
| 2. **Fixtures**: Use pytest fixtures from `tests/conftest.py` and `tests/fixtures/` | ||
| 3. **Markers**: Apply appropriate markers (`@pytest.mark.unit`, `@pytest.mark.e2e`, `@pytest.mark.comprehensive`) | ||
| 4. **Mocking**: Use `pytest-mock` for mocking, `responses` for HTTP mocking | ||
| 5. **Parametrization**: Use `@pytest.mark.parametrize` for testing multiple scenarios | ||
| 6. **Test Data**: Use `tests/fixtures/repos/` for example git repositories | ||
| ### Test Coverage | ||
| - Maintain high test coverage for core functionality | ||
| - Unit tests should be fast and not touch filesystem/network when possible | ||
| - E2E tests should test realistic workflows with actual git operations | ||
| ## Commit Message Conventions | ||
| This project uses **Conventional Commits** specification and is versioned by itself. | ||
| ### Format | ||
| ``` | ||
| <type>[optional scope]: <description> | ||
| [optional body] | ||
| [optional footer(s)] | ||
| ``` | ||
| ### Types | ||
| - `feat`: New feature (minor version bump) | ||
| - `fix`: Bug fix (patch version bump) | ||
| - `perf`: Performance improvement (patch version bump) | ||
| - `docs`: Documentation only changes | ||
| - `style`: Code style changes (formatting, missing semicolons, etc.) | ||
| - `refactor`: Code refactoring without feature changes or bug fixes | ||
| - `test`: Adding or updating tests | ||
| - `build`: Changes to build system or dependencies | ||
| - `ci`: Changes to CI configuration | ||
| - `chore`: Other changes that don't modify src or test files | ||
| ### Breaking Changes | ||
| - Add `!` after type/scope: `feat!: breaking change` | ||
| - Or add `BREAKING CHANGE:` in footer (major version bump) | ||
| ### Scopes | ||
| Use scopes where applicable to indicate the area of change: | ||
| - `cli`: CLI commands and interface | ||
| - `config`: Configuration handling | ||
| - `parser`: Commit message parsers | ||
| - `hvcs`: HVCS integrations (GitHub, GitLab, etc.) | ||
| - `changelog`: Changelog generation | ||
| - `version`: Version management | ||
| - etc. | ||
| ## Architecture | ||
| ### Key Modules | ||
| - `semantic_release/cli/`: Click-based CLI interface | ||
| - `commands/`: Individual CLI commands (version, changelog, publish) | ||
| - `config.py`: Configuration loading and validation with Pydantic | ||
| - `semantic_release/commit_parser/`: Commit message parsers | ||
| - `_base.py`: Base parser interface | ||
| - `angular.py`, `emoji.py`, `scipy.py`, `tag.py`: Parser implementations | ||
| - `semantic_release/hvcs/`: Hosting service integrations | ||
| - `_base.py`: Base HVCS interface | ||
| - `github.py`, `gitlab.py`, `gitea.py`, `bitbucket.py`: Service implementations | ||
| - `semantic_release/version/`: Version management | ||
| - `version.py`: Version class and comparison logic | ||
| - `translator.py`: Version translation between different formats | ||
| ### Design Patterns | ||
| - **Strategy Pattern**: Commit parsers and HVCS implementations are pluggable | ||
| - **Template Method**: Base classes define workflow, subclasses implement specifics | ||
| - **Builder Pattern**: Version calculation builds up changes from commits | ||
| - **Factory Pattern**: Parser and HVCS selection based on configuration | ||
| ## Building and Releasing | ||
| ### Local Build | ||
| ```bash | ||
| pip install -e .[build] | ||
| python -m build . | ||
| ``` | ||
| ### Release Process | ||
| This project releases itself automatically: | ||
| 1. Commits are analyzed from the default branch | ||
| 2. Version is determined based on commit types | ||
| 3. Changelog is generated from commits | ||
| 4. Package is built and published to PyPI | ||
| 5. GitHub release is created with changelog | ||
| ### Version Configuration | ||
| - Version stored in `pyproject.toml:project.version` | ||
| - Additional version locations in `tool.semantic_release.version_variables` | ||
| - Follows semantic versioning: MAJOR.MINOR.PATCH | ||
| ## Common Tasks | ||
| ### Adding a New Commit Parser | ||
| 1. Create new parser in `semantic_release/commit_parser/` | ||
| 2. Inherit from `CommitParser` base class | ||
| 3. Implement `parse()` method returning `ParseResult` | ||
| 4. Add parser to `KNOWN_COMMIT_PARSERS` in config | ||
| 5. Add tests in `tests/unit/semantic_release/commit_parser/` | ||
| ### Adding a New HVCS Integration | ||
| 1. Create new HVCS in `semantic_release/hvcs/` | ||
| 2. Inherit from `HvcsBase` base class | ||
| 3. Implement required methods (token creation, asset upload, release creation) | ||
| 4. Add HVCS to configuration options | ||
| 5. Add tests in `tests/unit/semantic_release/hvcs/` | ||
| ### Adding a New CLI Command | ||
| 1. Create command in `semantic_release/cli/commands/` | ||
| 2. Use Click decorators for arguments/options | ||
| 3. Access shared context via `ctx.obj` (RuntimeContext) | ||
| 4. Add command to main command group | ||
| 5. Add tests in `tests/e2e/cmd_<command>/` | ||
| ## Important Files | ||
| - `pyproject.toml`: Project configuration, dependencies, tool settings | ||
| - `action.yml`: GitHub Action definition | ||
| - `config/release-templates/`: Jinja2 templates for changelog and release notes | ||
| - `.pre-commit-config.yaml`: Pre-commit hooks configuration | ||
| - `CONTRIBUTING.rst`: Contribution guidelines | ||
| ## Documentation | ||
| - Hosted on ReadTheDocs: https://python-semantic-release.readthedocs.io | ||
| - Source in `docs/` directory | ||
| - Uses Sphinx with Furo theme | ||
| - Build locally: `sphinx-autobuild --open-browser docs docs/_build/html` | ||
| ## Python Version Support | ||
| - Minimum: Python 3.8 | ||
| - Tested on: Python 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 | ||
| - Target version for type checking: Python 3.8 | ||
| ## Dependencies to Know | ||
| - **Click**: CLI framework | ||
| - **GitPython**: Git operations | ||
| - **Pydantic v2**: Configuration validation and models | ||
| - **Jinja2**: Template engine for changelogs | ||
| - **requests**: HTTP client for HVCS APIs | ||
| - **python-gitlab**: GitLab API client | ||
| - **tomlkit**: TOML parsing with formatting preservation | ||
| - **rich**: Rich terminal output | ||
| ## Helpful Tips | ||
| - When modifying configuration, update the Pydantic models in `cli/config.py` | ||
| - Changelog templates are in `config/release-templates/` - use Jinja2 syntax | ||
| - The `RuntimeContext` object holds shared state across CLI commands | ||
| - Use `--noop` flag to test commands without making changes | ||
| - Version detection respects git tags - use annotated tags | ||
| - The project uses its own tool for versioning, so commit messages matter! |
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.