docs: add CONTRIBUTING, CLA, CoC, CONTRIBUTORS and CLA workflows (#18)

.github/workflows/ci.yml

@@ -177,6 +177,10 @@ jobs:
             README.md
             SECURITY.md
             CHANGELOG.md
+            CONTRIBUTING.md
+            CLA.md
+            CODE_OF_CONDUCT.md
+            CONTRIBUTORS.md
 
   bdd-strict-mode-guard:
     name: BDD strict mode guard

.github/workflows/cla.yml

@@ -0,0 +1,65 @@
+name: "CLA Assistant"
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened, closed, synchronize]
+
+# Explicit permissions because repository-level workflow permissions
+# may be read-only. The PAT below carries the actual push authority
+# through branch protection; GITHUB_TOKEN is used for PR comments and
+# status updates.
+permissions:
+  actions: write
+  contents: write
+  pull-requests: write
+  statuses: write
+
+jobs:
+  CLAAssistant:
+    runs-on: ubuntu-latest
+    # Skip unless the trigger is either a relevant PR event or a comment
+    # that looks like a signature / recheck request. The action filter
+    # inside the step duplicates this; having it at the job level avoids
+    # spinning up a runner for unrelated `issue_comment` events.
+    if: |
+      github.event_name == 'pull_request_target' ||
+      (github.event_name == 'issue_comment' &&
+        (github.event.comment.body == 'recheck' ||
+         github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA'))
+    steps:
+      - name: CLA Assistant
+        uses: contributor-assistant/github-action@v2.6.1
+        env:
+          # GITHUB_TOKEN is used for PR interactions (comments, status
+          # checks). The default in-built token is sufficient for those.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # PERSONAL_ACCESS_TOKEN drives the commit that records the
+          # signature. Using an admin-scoped PAT lets the write bypass
+          # branch protection on `main` (required-PR, required-signatures)
+          # while still producing a GitHub web-flow-signed commit.
+          # The secret is created manually at:
+          #   Settings → Secrets and variables → Actions → CLA_ASSISTANT_PAT
+          PERSONAL_ACCESS_TOKEN: ${{ secrets.CLA_ASSISTANT_PAT }}
+        with:
+          path-to-signatures: "signatures/version1/cla.json"
+          path-to-document: "https://github.com/axonops/syncmap/blob/main/CLA.md"
+          branch: "main"
+          # Allowlisted accounts do not need to sign the CLA. Bots only —
+          # humans always go through the check so they are recorded in
+          # the signatures file and the public CONTRIBUTORS.md list.
+          allowlist: "dependabot[bot],renovate[bot],github-actions[bot]"
+          custom-notsigned-prcomment: |
+            Thank you for your contribution! Before we can merge this PR, you need to sign our [Contributor License Agreement](https://github.com/axonops/syncmap/blob/main/CLA.md).
+
+            **To sign**, post a comment on this PR containing exactly:
+
+            > I have read the CLA Document and I hereby sign the CLA
+
+            The CLA is a one-time agreement that covers every future contribution you make to any AxonOps open-source project. If you have questions before signing, please open a discussion or email `oss@axonops.com`.
+          custom-pr-sign-comment: "I have read the CLA Document and I hereby sign the CLA"
+          custom-allsigned-prcomment: "All contributors have signed the CLA. ✅"
+          signed-commit-message: "chore(cla): $contributorName signed the CLA in #$pullRequestNo"
+          create-file-commit-message: "chore(cla): initialise signatures file"
+          lock-pullrequest-aftermerge: true

.github/workflows/contributors.yml

@@ -0,0 +1,53 @@
+name: "Contributors list"
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "signatures/version1/cla.json"
+
+# CLA signatures trigger a CONTRIBUTORS.md regeneration. The commit
+# that pushed the signature is skipped via [skip ci] conventions
+# elsewhere, but this workflow only triggers on the signatures path
+# so unrelated main-branch pushes do not spin up this runner.
+permissions:
+  contents: write
+
+jobs:
+  regenerate:
+    name: Regenerate CONTRIBUTORS.md
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          # Use the admin PAT so the commit pushed at the end of this
+          # job bypasses branch protection on `main`. GITHUB_TOKEN can
+          # read but cannot write through `required_pull_request_reviews`.
+          # The secret is created manually at:
+          #   Settings → Secrets and variables → Actions → CLA_ASSISTANT_PAT
+          token: ${{ secrets.CLA_ASSISTANT_PAT }}
+          fetch-depth: 0
+
+      - name: Install jq
+        run: |
+          # jq ships on ubuntu-latest by default, but install if absent.
+          command -v jq >/dev/null 2>&1 || sudo apt-get install -y jq
+
+      - name: Regenerate CONTRIBUTORS.md
+        run: ./scripts/generate-contributors.sh
+
+      - name: Commit and push if changed
+        run: |
+          set -euo pipefail
+
+          if git diff --quiet CONTRIBUTORS.md; then
+            echo "CONTRIBUTORS.md unchanged — nothing to commit."
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git add CONTRIBUTORS.md
+          git commit -m "chore(contributors): regenerate CONTRIBUTORS.md"
+          git push origin main

CLA.md

@@ -0,0 +1,160 @@
+# AxonOps Contributor License Agreement
+
+This is the Contributor License Agreement ("CLA") for the open-source
+projects operated by AxonOps Limited on GitHub, including
+`github.com/axonops/syncmap` and any other repository under the `axonops`
+GitHub organisation that references this document.
+
+## Plain-English summary
+
+You keep the copyright to everything you contribute. By signing this
+CLA once, you grant AxonOps permission to include your contributions
+in any AxonOps open-source project and to relicense them in future
+versions of that project, under the project's stated licence (Apache
+Licence 2.0 for `syncmap`). You also confirm that the work is yours to
+contribute — that it is your own, that your employer does not have a
+conflicting claim, and that it does not knowingly include anyone
+else's proprietary code.
+
+You only sign this CLA once per GitHub account. The signature covers
+every AxonOps project forever, past and future.
+
+**Signing this CLA does NOT change your rights to use, modify, or
+redistribute your own contributions however you wish.**
+
+If anything in the full text below is unclear, please open a discussion
+on the repository before signing. We are happy to explain.
+
+---
+
+## 1. Definitions
+
+- **"You"** (or **"Your"**) means the copyright owner or the legal
+  entity authorised by the copyright owner that is making this
+  Agreement with AxonOps Limited ("AxonOps").
+
+- **"Contribution"** means any original work of authorship, including
+  any modifications or additions to an existing work, that is
+  intentionally submitted by You to AxonOps for inclusion in, or
+  documentation of, any of the open-source projects operated by
+  AxonOps (each a "Project").
+
+- **"Submitted"** means any form of electronic, verbal, or written
+  communication sent to AxonOps or its representatives, including but
+  not limited to communication on pull requests, issues, discussions,
+  and email, that is intentionally submitted by You for inclusion in
+  a Project.
+
+## 2. Grant of copyright licence
+
+Subject to the terms and conditions of this Agreement, You hereby
+grant to AxonOps Limited and to recipients of software distributed by
+AxonOps a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright licence to reproduce, prepare derivative works
+of, publicly display, publicly perform, sublicense, and distribute
+Your Contributions and such derivative works.
+
+## 3. Grant of patent licence
+
+Subject to the terms and conditions of this Agreement, You hereby
+grant to AxonOps Limited and to recipients of software distributed by
+AxonOps a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable (except as stated in this section) patent licence to make,
+have made, use, offer to sell, sell, import, and otherwise transfer
+the Project, where such licence applies only to those patent claims
+licensable by You that are necessarily infringed by Your Contribution(s)
+alone or by combination of Your Contribution(s) with the Project to
+which such Contribution(s) was submitted. If any entity institutes
+patent litigation against You or any other entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that your
+Contribution, or the Project to which you have contributed, constitutes
+direct or contributory patent infringement, then any patent licences
+granted to that entity under this Agreement for that Contribution or
+Project shall terminate as of the date such litigation is filed.
+
+## 4. Representations
+
+4.1. You represent that You are legally entitled to grant the above
+licences. If Your employer(s) has rights to intellectual property
+that You create that includes Your Contributions, You represent that
+You have received permission to make Contributions on behalf of that
+employer, that Your employer has waived such rights for Your
+Contributions to AxonOps, or that Your employer has executed a
+separate Corporate CLA with AxonOps.
+
+4.2. You represent that each of Your Contributions is Your original
+creation (see Section 5 for submissions on behalf of others).
+
+4.3. You represent that Your Contribution submissions include
+complete details of any third-party licence or other restriction
+(including, but not limited to, related patents and trademarks) of
+which You are personally aware and which are associated with any part
+of Your Contributions.
+
+## 5. Third-party content
+
+Should You wish to submit work that is not Your original creation,
+You may submit it to AxonOps separately from any Contribution,
+identifying the complete details of its source and of any licence or
+other restriction (including, but not limited to, related patents,
+trademarks, and licence agreements) of which You are personally
+aware, and conspicuously marking the work as "Submitted on behalf of
+a third-party: [named here]".
+
+## 6. Support
+
+You are not expected to provide support for Your Contributions,
+except to the extent You desire to provide support. You may provide
+support for free, for a fee, or not at all. Unless required by
+applicable law or agreed to in writing, You provide Your Contributions
+on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+either express or implied, including, without limitation, any
+warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY,
+or FITNESS FOR A PARTICULAR PURPOSE.
+
+## 7. Notification
+
+You agree to notify AxonOps of any facts or circumstances of which
+You become aware that would make these representations inaccurate in
+any respect.
+
+## 8. No modification of Your rights
+
+Nothing in this Agreement restricts Your right to use, modify, or
+redistribute Your own Contributions under any terms. AxonOps does
+not acquire ownership of Your contributions — only the licences
+granted above.
+
+## 9. Scope
+
+This Agreement applies to all open-source projects operated by
+AxonOps Limited under the `axonops` GitHub organisation. Signing it
+once covers all past and future Contributions to any such project.
+
+---
+
+## How to sign
+
+Signing is done automatically by our CLA Assistant bot the first time
+you open a pull request against any AxonOps open-source repository.
+
+1. Open your first pull request.
+2. The bot will comment asking you to sign.
+3. Reply to the pull request with exactly:
+
+   > I have read the CLA Document and I hereby sign the CLA
+
+4. Your signature is recorded in `signatures/version1/cla.json` with your
+   GitHub username, the pull request reference, and a timestamp.
+5. The human-readable list of everyone who has signed lives at
+   [`CONTRIBUTORS.md`](./CONTRIBUTORS.md) and is regenerated
+   automatically each time the signatures file changes.
+
+If you prefer to sign outside GitHub (for example, as an organisation
+signing on behalf of employees), please email `oss@axonops.com` and
+we will work with you to put a Corporate CLA in place.
+
+---
+
+_This Agreement is adapted from the Apache Software Foundation
+Individual Contributor License Agreement v2.2._

CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at oss@axonops.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations