From 934587091f8b56f9c7b655cbeb01605c0862cedb Mon Sep 17 00:00:00 2001 From: Sean Sica <23294618+seansica@users.noreply.github.com> Date: Mon, 21 Oct 2024 17:05:06 -0400 Subject: [PATCH] docs: update README.md and docs/CONTRIBUTING.md * Add link to GitHub Pages SSG to README. * Update CONTRIBUTING.md with our versioning and release process. --- README.md | 6 +++ docs/CONTRIBUTING.md | 106 ++++++++++++++++++++++++++++++++++++++----- 2 files changed, 100 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index bcd05ac..a064761 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,12 @@ The ATT&CK Data Model (ADM) is a TypeScript library that provides a structured way to interact with MITRE ATT&CK datasets. It uses Zod schemas, TypeScript types, and ES6 classes to create a type-safe, object-oriented interface for navigating the ATT&CK data model. This library is designed to parse, validate, and serialize STIX 2.1 formatted content, making it easy to work with ATT&CK-related data in a programmatic and intuitive way. +You can browse the ATT&CK schemas in a user-friendly interface at: + +https://mitre-attack.github.io/attack-data-model/. + +This site is dynamically generated from the contents of the `@latest` distribution channel / `main` branch. Please note that we do not currently maintain separate documentation for previous releases. + ## Features - **Type-Safe Data Parsing**: ADM validates STIX 2.1 bundles using Zod schemas, ensuring data model compliance and type safety. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 625c870..ffaacec 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -79,25 +79,107 @@ We use **eslint-config-prettier** to disable any formatting rules in ESLint that ### Husky and Git Hooks - **Husky**: We use Husky to add Git hooks that automate certain tasks before commits and pushes. - - **Pre-Commit Hook**: Husky runs `npm run format` before every commit. This command runs both Prettier and ESLint in fix mode to ensure all code is properly formatted and adheres to linting rules before it is committed. - - **Pre-Push Hook**: Husky also runs `npm run test` before pushing to the repository. This ensures that all tests pass before the code is pushed, preventing broken code from entering the remote branches. +- **Pre-Commit Hook**: Husky runs `npm run format` before every commit. This command runs both Prettier and ESLint in fix mode to ensure all code is properly formatted and adheres to linting rules before it is committed. +- **Pre-Push Hook**: Husky also runs `npm run test` before pushing to the repository. This ensures that all tests pass before the code is pushed, preventing broken code from entering the remote branches. +- **Commit-Msg Hook**: Husky also runs `npx --no-install commitlint --edit` before accepting a commit. This ensures that all commit messages adhere to the conventional commit format, thereby keeping semantic-release happy. These hooks help enforce code quality and consistency across all contributions, making it easier to maintain the project over time. -## Versioning +## Versioning and Release Process -We use [SemVer](http://semver.org/) for versioning. For version bumps, use the following npm commands: +We use semantic-release to manage all aspects of the release process. It automatically determines the next version number, creates git tags, generates release notes, and publishes the package to the GitHub Package Registry for npm artifacts. -### For pre-release versions (e.g., 1.0.0-rc.0): -- To increment to the next pre-release (e.g., 1.0.0-rc.1): `npm version prerelease` -- To bump to the release version (e.g., 1.0.0): `npm version minor` (or `npm version major` if it's a major release) +### Semantic Release Configuration -### For release versions (e.g., 1.0.0): -- To bump the patch version (e.g., 1.0.0 to 1.0.1): `npm version patch` -- To bump the minor version (e.g., 1.0.0 to 1.1.0): `npm version minor` -- To bump the major version (e.g., 1.0.0 to 2.0.0): `npm version major` +We use the default semantic-release configuration, which includes the following plugins (in order of execution): -Please ensure you update the version number appropriately with your changes. +1. "@semantic-release/commit-analyzer" +2. "@semantic-release/release-notes-generator" +3. "@semantic-release/npm" +4. "@semantic-release/github" + +These plugins are part of semantic-release and do not need to be installed separately. + +### Release Workflow and Distribution Channels + +Our release workflow follows semantic-release's default configuration, which uses different branches for different types of releases and distribution channels: + +- Main release channel (`@latest`): + - Branches: `master`, `main` + - This is the default channel for stable releases. + +- Next release channel (`@next`): + - Branches: `next`, `next-major` + - Used for upcoming feature releases or major version changes. + +- Maintenance release channels: + - Branch pattern: `+([0-9])?(.{+([0-9]),x}).x` + - Example: `2.x` or `2.1.x` + - Used for maintenance releases of older versions. + +- Pre-release channels: + - Branches: `beta` (`@beta` channel), `alpha` (`@alpha` channel) + - Used for pre-release versions. + +### How It Works + +1. **Commit Messages**: When you make changes, use [Conventional Commits](https://www.conventionalcommits.org/) syntax for your commit messages. This helps semantic-release determine the type of changes and the appropriate version increment. + + Examples: + - `feat: add new attack technique` (triggers a minor version bump) + - `fix: correct typo in technique description` (triggers a patch version bump) + - `feat!: rename primary data structure` (triggers a major version bump) + +2. **Husky**: We use Husky to enforce compliance with Conventional Commits syntax. It runs a commit message linter before each commit to ensure your messages follow the correct format. + +3. **Branching**: Choose the appropriate branch for your work: + - For regular features and fixes, work on `main`. + - For major changes or experimental features, use `next` or `next-major`. + - For bug fixes to older versions, use the appropriate maintenance branch (e.g., `2.x`). + - For pre-release features, use `beta` or `alpha`. + +4. **Pull Requests**: When your changes are ready, create a pull request to the appropriate branch. + +5. **Merging**: Once approved and merged, semantic-release takes over: + - It analyzes the commit messages since the last release. + - Determines the new version number based on the changes. + - Creates a new git tag for the release. + - Generates release notes. + - Publishes the package to npm with the appropriate dist-tag. + +### Examples + +1. Regular feature addition: + - Work on `main` branch + - Commit with message: `feat: add MITRE ATT&CK v10 techniques` + - After merge, semantic-release might create version `1.1.0` on the `@latest` channel + +2. Critical bug fix: + - Work on `main` branch + - Commit with message: `fix: resolve data corruption in technique lookup` + - After merge, semantic-release might create version `1.1.1` on the `@latest` channel + +3. Major breaking change: + - Work on `next-major` branch + - Commit with message: `feat!: restructure data model for performance improvements` + - After merge, semantic-release might create version `2.0.0-next.1` on the `@next` channel + +4. Maintenance fix for older version: + - Work on `1.x` branch + - Commit with message: `fix: address compatibility issue with Node.js 14` + - After merge, semantic-release might create version `1.2.1` on a `@release-1.x` channel + +### Version Management + +The `version` property in `package.json` is not actively tracked. To make it clear to contributors that the version is not kept up to date, we use the value `0.0.0-semantically-released`. For more information on this approach, please refer to the semantic-release [FAQ](https://github.com/semantic-release/semantic-release/blob/master/docs/support/FAQ.md#making-commits-during-the-release-process-adds-significant-complexity). + +### Further Reading + +For more detailed information on specific release scenarios, please refer to the following example workflows maintained by semantic-release: + +- [Publishing on distribution channels](https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/release-workflow/distribution-channels.md) +- [Publishing maintenance releases](https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/release-workflow/maintenance-releases.md) +- [Publishing pre-releases](https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/release-workflow/pre-releases.md) ## Questions?