Skip to content

Commit 5797a2f

Browse files
seansicaseansica
committed
docs: update release+contrib documentation
1 parent 3a49500 commit 5797a2f

File tree

2 files changed

+94
-80
lines changed

2 files changed

+94
-80
lines changed

‎docs/CONTRIBUTING.md‎

Lines changed: 57 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,65 @@
11
# Contributors
22

33
## Reporting Issues
4-
If you encounter an issue with the `mitreattack-python` library, please let us know by filing a [Github issue](https://github.com/mitre-attack/mitreattack-python/issues). When doing so, please make sure you provide the following information:
5-
* Describe (in detail as possible) what occurred and what you were expecting to occur. Any information you can provide, such stack traces or errors are very helpful.
6-
* Describe the steps necessary to replicate the issue.
7-
* Indicate your OS and python versions.
4+
5+
If you encounter an issue with the `mitreattack-python` library, please let us know by filing a [GitHub issue](https://github.com/mitre-attack/mitreattack-python/issues). When doing so, please make sure you provide the following information:
6+
7+
- Describe (in as much detail as possible) what occurred and what you were expecting to occur. Any information you can provide, such as stack traces or errors, is very helpful.
8+
- Describe the steps necessary to replicate the issue.
9+
- Indicate your OS and Python versions.
810

911
## Suggested New Features
10-
If you have an idea for a new feature for `mitreattack-python`, please let us know by filing a [Github issue](https://github.com/mitre-attack/mitreattack-python/issues). When doing so, please make sure you provide the following information:
11-
* Explain the functionality you are proposing, and its use case - what would it be useful for or allow you to do?
12-
* List what existing ATT&CK tools or resources map to the proposed functionality
13-
* If applicable, provide examples of other requests for the proposed functionality
12+
13+
If you have an idea for a new feature for `mitreattack-python`, please let us know by filing a [GitHub issue](https://github.com/mitre-attack/mitreattack-python/issues). When doing so, please make sure you provide the following information:
14+
15+
- Explain the functionality you are proposing, and its use case — what would it be useful for or allow you to do?
16+
- List what existing ATT&CK tools or resources map to the proposed functionality.
17+
- If applicable, provide examples of other requests for the proposed functionality.
1418

1519
## Developing
16-
If you want to work on the `mitreattack-python` library and contribute to its ongoing development, we welcome merge requests! You can set up an environment for development by following this process:
17-
1. Clone the repository - `git clone https://github.com/mitre-attack/mitreattack-python`.
18-
2. Create a virtual environment, and activate it - `python3 -m venv venv`/`. venv/bin/activate`.
19-
3. Install the appropriate python modules via pip - `pip install -r requirements-dev.txt`.
2020

21-
### Merge Requests
22-
When making a merge request, please make sure to include a summary of what the changes are intended to do, functionality wise, and the testing performed to validate the changes (ideally in the form of new pytests integrated into the `tests/` collection, though this is not strictly required). In addition, the complete pytest test battery `tests/` must be passed without errors in order for any code to actually be merged.
21+
We welcome pull requests! To set up a local development environment:
22+
23+
### Prerequisites
24+
25+
- [Python 3.11+](https://www.python.org/downloads/)
26+
- [uv](https://docs.astral.sh/uv/getting-started/installation/) — fast Python package manager
27+
- [just](https://github.com/casey/just#installation) — command runner (optional, but recommended)
28+
29+
### Setup
30+
31+
```bash
32+
# Clone the repository
33+
git clone https://github.com/mitre-attack/mitreattack-python
34+
cd mitreattack-python
35+
36+
# Install all dependencies (including dev and docs extras)
37+
just install
38+
# or without just:
39+
uv sync --all-extras
40+
41+
# (Optional) Install pre-commit hooks for local linting and commit message validation
42+
just setup-hooks
43+
# or without just:
44+
uv run pre-commit install
45+
uv run pre-commit install --hook-type commit-msg
46+
```
47+
48+
### Common Commands
49+
50+
Run `just` with no arguments to see all available commands. Here are the most common ones:
51+
52+
```bash
53+
just lint # Run pre-commit hooks (ruff format) on all files
54+
just test # Run tests
55+
just test-cov # Run tests with coverage report
56+
just build # Build the package
57+
```
58+
59+
### Pull Requests
60+
61+
When making a pull request, please make sure to:
62+
63+
- Include a summary of what the changes are intended to do and the testing performed to validate them (ideally in the form of new pytests in the `tests/` collection, though this is not strictly required).
64+
- **Use a [Conventional Commits](https://www.conventionalcommits.org) formatted PR title** (e.g., `feat: add new export format`, `fix: handle missing data sources`). PRs are squash-merged, so the PR title becomes the merge commit message — individual commit messages within the PR do not need to follow any convention.
65+
- All pytest tests in `tests/` must pass, and ruff linting/formatting checks must be clean.

‎docs/RELEASE.md‎

Lines changed: 37 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,63 @@
11
# Release Process
22

3-
This guide walks maintainers through releasing a new version of **mitreattack-python**.
4-
The process uses [Poetry](https://python-poetry.org/) for dependency management and building,
5-
and [GitHub Actions](https://github.com/mitre-attack/mitreattack-python/actions) for automated linting, testing, and publishing to PyPI.
3+
Releases of **mitreattack-python** are fully automated. When commits are pushed (or squash-merged) to `main`, [Python Semantic Release (PSR)](https://python-semantic-release.readthedocs.io/) analyzes the commit messages and, if warranted, bumps the version, tags the release, creates a GitHub Release, and publishes the package to PyPI — all within the [CI pipeline](https://github.com/mitre-attack/mitreattack-python/actions).
64

7-
## 1. Prepare for Release
5+
## How It Works
86

9-
- Ensure all desired changes are merged into the `main` branch.
10-
- If releasing for a new ATT&CK version, update `LATEST_VERSION` in `mitreattack/release_info.py`.
7+
1. **Commit messages drive versioning.** We follow the [Conventional Commits](https://www.conventionalcommits.org) specification. PSR parses commit messages to determine the appropriate [SemVer](https://semver.org/) bump:
118

12-
## 2. Update Version and Metadata
9+
| Commit prefix | Version bump | Example |
10+
|---|---|---|
11+
| `feat:` | Minor (`0.X.0`) | `feat: add analytics to excel output` |
12+
| `fix:`, `perf:` | Patch (`0.0.X`) | `fix: handle missing data sources` |
13+
| `BREAKING CHANGE` in footer, or `!` after type | Major (`X.0.0`) | `feat!: drop Python 3.10 support` |
14+
| `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `test:` | No release | `ci: update uv setup action` |
1315

14-
- Run `cz bump --files-only`
15-
- This will increment the version field in `pyproject.toml` and other places according to semantic versioning rules.
16-
- It will also update the `CHANGELOG.md` with all commit messages that are compatible with [Conventional Commits](https://www.conventionalcommits.org).
17-
- NOTE: You should double-check the generated `CHANGELOG.md` file and make sure it looks good.
18-
- Update other metadata as needed in `pyproject.toml` (dependencies, etc.).
19-
- `poetry update --with dev --with docs`
16+
2. **PRs are squash-merged.** Individual commits within a PR do not need to follow conventional commits — only the PR title matters, as it becomes the squash merge commit message. The [`pr-title.yml`](../.github/workflows/pr-title.yml) workflow validates PR titles on open.
2017

21-
## 3. Local Validation (Recommended)
18+
3. **On push to `main`, the CI pipeline** (`.github/workflows/ci.yml`) runs:
19+
- **commitlint** — validates the squash merge commit message
20+
- **lint** — ruff check and format verification
21+
- **test** — pytest with coverage
22+
- **release** — PSR evaluates commits since the last tag, bumps version, tags, and creates a GitHub Release with build artifacts
23+
- **publish** — uploads the package to PyPI via trusted publishing (OIDC)
2224

23-
Before tagging and pushing, validate the release locally. Following these steps:
25+
## For Maintainers
2426

25-
```bash
26-
# Pre-requisite: Install Poetry if not already installed
27-
# https://python-poetry.org/docs/#installing-with-the-official-installer
28-
curl -sSL https://install.python-poetry.org | python3 -
27+
### Triggering a Release
28+
29+
No manual steps are needed. Simply merge a PR to `main` with a conventional commit title that includes a release-triggering prefix (`feat:`, `fix:`, or `perf:`). PSR will handle the rest.
2930

30-
# Clean previous builds
31-
rm -rf dist/
31+
### Pre-release Validation (Optional)
3232

33+
If you want to validate locally before merging:
34+
35+
```bash
3336
# Install dependencies (including dev tools)
34-
poetry install --with=dev
37+
just install
3538

3639
# Lint and format
37-
poetry run ruff check
38-
poetry run ruff format --check
40+
just lint
3941

40-
# Build docs
41-
# This is managed directly by the Readthedocs site which is configured to watch our repository, but we should test it locally too
42-
# https://app.readthedocs.org/projects/mitreattack-python/
43-
cd docs/
44-
poetry run python -m sphinx -T -b html -d _build/doctrees -D language=en . _build/html
45-
cd ..
46-
47-
# Run tests
48-
poetry run pytest --cov=mitreattack --cov-report html
42+
# Run tests with coverage
43+
just test-cov
4944

5045
# Build the package
51-
poetry build
46+
just build
5247

5348
# (Optional) Validate wheel contents
54-
poetry run check-wheel-contents dist/
55-
56-
# (Optional) Install locally and smoke test
57-
poetry run pip install --find-links=./dist mitreattack-python
58-
poetry run python -c "import mitreattack; print(mitreattack.__version__)"
59-
```
60-
61-
## 4. Commit and Tag the Release
49+
uv run check-wheel-contents dist/
6250

63-
Make sure that after the above local testing you commit all changes!
64-
65-
Perform the following steps to tag the release and push to GitHub:
66-
67-
```bash
68-
# Tag the release
69-
git tag -a "vX.Y.Z" -m "mitreattack-python version X.Y.Z"
70-
71-
# Push the commit and tag
72-
git push
73-
git push --tags
51+
# (Optional) Dry run semantic release
52+
just release-dry-run
7453
```
7554

76-
## 5. Automated Publishing
77-
78-
Once the tag is pushed to GitHub:
79-
80-
- GitHub Actions will automatically lint, test, build, and publish the package to PyPI using the workflow in `.github/workflows/lint-publish.yml`.
81-
82-
## 6. Verify Release
83-
84-
Check the [GitHub Actions](https://github.com/mitre-attack/mitreattack-python/actions) for a successful workflow run.
55+
### Updating ATT&CK Version Metadata
8556

86-
Confirm the new version is available on [PyPI](https://pypi.org/project/mitreattack-python/).
57+
If releasing for a new ATT&CK version, update `LATEST_VERSION` in `mitreattack/release_info.py` before merging.
8758

8859
## Notes
8960

90-
- All build and publish steps are handled by GitHub Actions once you push the tag.
91-
- Manual local validation is optional but recommended before tagging.
92-
- Readthedocs is used for documentation builds. [Check the status here](https://app.readthedocs.org/projects/mitreattack-python/).
61+
- All build, release, and publish steps are handled by GitHub Actions — no manual tagging or uploading.
62+
- Version is tracked in `pyproject.toml` (`project.version`) and synced to `docs/conf.py` and `mitreattack/__init__.py` by PSR.
63+
- Documentation builds are managed by [ReadTheDocs](https://app.readthedocs.org/projects/mitreattack-python/), which watches the repository.

0 commit comments

Comments
 (0)