Skip to content

Latest commit

 

History

History
103 lines (63 loc) · 4.88 KB

GOVERNANCE.rst

File metadata and controls

103 lines (63 loc) · 4.88 KB
Raw

Kestrel Language Development

Maintainers and Contributors

Find the current maintainers and contributors to the project at our authors page.

GitHub Issue Management

Maintainers subscribe to the project and get notification of GitHub issue creation and updates. At least one maintainer needs to participate in a GitHub issue after created.

Code Contribution Management

Maintainers subscribe to the project and get notification of pull requests (PR). For bug fix PR, at least one maintainer needs to review and approve the PR before merging to the develop branch. For new feature PR, one maintainer will lead the discussion to review and merge it.

Branching Model

This repo generally follow the branching model summarized by Vincent Driessen. The two long-term branches are develop and release.

Semantic Versioning

Kestrel language repo uses the following semantic versioning rules before OCA-wide versioning guideline is established:

  • A package is released with version Major.Minor.Patch.

  • Major number: This should be incremented every time there is dramatic model change of the Kestrel language, e.g., entity-based cyber reasoning is established from v0 to v1, which rules how variables are defined/used, how to pivot between hunt steps, and how the composition of hunt-flow is performed.

  • Minor number: This should be incremented every time important features are introduced, which could make backward incompatible changes to the language or interfaces, but not dramatically change the language model. Examples:

    • A new feature realizes a new capability within the scope of the existing architecture or design concept, e.g., new analytics interface, it should be a new minor number.
    • A new command is added to syntax within the scope of existing architecture, e.g., CONFIG for dynamically updating configuration in a session, GENERATE REPORT to generate hunting report from the hunt-flow.
    • A dramatic improvement of the internal data model, e.g., firepit supports full entity-based graph schema.

  • Patch number: This should be incremented every time small improvement features are added, bugs are fixed, and other small updates that do not change the language syntax or interface.

Release Procedure

A maintainer should release a new Kestrel runtime (PyPI package name: kestre-lang) following the procedure:

  1. Update version and changelog

    1. Sync the local git repo to the latest of the develop branch.
    2. Update the version field in packages/*/pyproject.toml for any package that has been updated.
    3. Update dependencies in packages/*/pyproject.toml.
    4. Always bump the version field in packages/kestrel_jupyter/pyproject.toml (the umbrella package).
    5. Add changes in CHANGELOG.rst under the umbrella package version.
    6. Add new contributors to AUTHORS.rst if any.
    7. Commit the updates with the umbrella package version as the message.
    8. Push the local develop branch to remote.

  2. Graduate code to the release branch

    1. Open a PR to merge the develop branch to the release branch. Use umbrella package version as the PR title.
    2. Merge the PR.

  3. Create a new release

    1. Go to the release page and click Draft a new release.

    2. Type the umbrella package version number as the new tag to create.

    3. Choose release branch as the Target.

    4. Specify a release title. Use the date for ordinary release.

    5. Write a summary of the release.

      • Patch number release: copy the CHANGELOG entries.
      • Minor number release: may have a TLDR at the beginning highlighting the most important new feature.

    6. Hit the Publish release button.

  4. After release check

Vulnerability Disclosure

In the case of a vulnerability, please contact any of the maintainers via slack to resolve the vulnerability as soon as possible (before or after it is published). To join OCA slack workspace, please follow the instructions in the README.