Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
97 lines (68 loc) · 3.85 KB

CONTRIBUTING.md

File metadata and controls

97 lines (68 loc) · 3.85 KB

🌿 Branching Strategy

We follow a Feature Branch workflow. All development must occur on branches and be merged into main via Pull Request.

  • main: Stable, production-ready code.
  • feat/*: New features or standard updates (e.g., feat/new-message-support).
  • fix/*: Bug fixes.
  • chore/*: Maintenance tasks (CI/CD, dependencies, licenses).

📝 Commit Message Standards

We use the Conventional Commits specification. This allows for automated changelog generation and versioning.

Format: <type>: <description>

  • init: Initial project setup or raw source imports.
  • feat: A new feature or binding.
  • fix: A bug fix.
  • build: Changes to build system (CMake, Makefile, emsdk).
  • test: Adding or correcting tests.
  • docs: Documentation updates.
  • style: Linting or formatting.
  • refactor: Cleaning up code without changing what it does.
  • ci: Changes to GitHub Actions or CI pipeline.

Example: feat: add Python bindings for RSA messages

🛠 Development Workflow

  1. Branch: Create a branch from main.
  2. Version: If your change introduces a new feature or bug fix, increment the version in both CMakeLists.txt and language bindings.
  3. Build: Use make to ensure C++ and WASM artifacts are up to date.
  4. Test: Run tests.
  5. Lint: Ensure code is formatted properly formatted in whatever language they come in.

🔢 Versioning Policy

This project uses Semantic Versioning (SemVer). Because this is a multi-language project, we enforce a Unified Versioning Strategy.

1. Unified Version Sync

The version number must be identical across all configuration files. Versioning can be sycned using the Makefile. Here are the instructions:

  1. Edit the VERSION file in the root directory to desired value.
  2. Run the command: make sync-version.

2. When to Increment

  • MAJOR (X.0.0): Significant breaking changes to the API or a major update that breaks backward compatibility.
  • MINOR (1.X.0): Adding support for new features that are backward compatible.
  • PATCH (1.0.X): Bug fixes or documentation updates.

🚀 CI/CD & Automated Releasing

We use GitHub Actions to automate the compilation of WASM core logic, run cross-language tests, and package releases.

1. The Workflow Pipeline

The CI pipeline runs on every push and pull request, but it behaves differently depending on the "ref":

- Pull Requests / Branch Pushes: Runs the WASM Build and Python Test Suite. These must pass before a PR can be merged.
- Tag Pushes (v*): Triggers the full pipeline including the Publish Release stage.

2. How to Release a New Version

Releases are strictly triggered by Git tags. We follow Semantic Versioning (SemVer).

To trigger a production release:

  1. Ensure your changes are merged into main.
  2. Create a tag: git tag v1.0.0.
  3. Push the tag: git push origin v1.0.0.

To trigger a test/pre-release: If your tag contains the strings test, alpha, or beta, the system will automatically mark the GitHub Release as a Pre-release (non-production).

git tag v1.0.0-test.1
git push origin v1.0.0-test.1

3. Release Artifacts

Every successful tag push generates a unified GitHub Release containing:

  • Python Wheels (.whl): Pre-compiled packages including the WASM binaries.
  • Source Distributions (.tar.gz): The raw source code.
  • Core WASM Binaries: The raw .wasm and .js files (found in the release-wasm/ asset folder) for non-Python use cases.

🔍 Summary of Tagging Rules for Contributors

Tag Pattern Release Type GitHub Badge
v1.2.3 Production Latest
v1.2.3-test.1 Internal Test Pre-release
v1.2.3-alpha.0 Early Access Pre-release

📬 Pull Request Process

  1. Ensure the CI pipeline passes.
  2. Provide a description of the changes and a link to any relevant documentation.
  3. At least one peer review is required before merging.