Skip to content

Commit 99244b1

Browse files
pm-McFlypm-McFly
authored
Introduces Coding Standards and Contribution Guidelines (#341)
Signed-off-by: Pierre 'McFly' Marty <pmarty@linagora.com>
1 parent 6f46324 commit 99244b1

File tree

37 files changed

+2887
-4119
lines changed

37 files changed

+2887
-4119
lines changed

‎.eslintrc.cjs‎

Lines changed: 0 additions & 16 deletions
This file was deleted.

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
name: Bug report
2+
description: Something does not behave as expected.
3+
labels: ["bug"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Before filing: search open and closed issues to avoid duplicates.
9+
Fill every required field — incomplete reports will be closed.
10+
11+
- type: dropdown
12+
id: package
13+
attributes:
14+
label: Package
15+
description: Which package is affected?
16+
options:
17+
- amqp-connector
18+
- common-settings-bridge
19+
- config-parser
20+
- crypto
21+
- db
22+
- federated-identity-service
23+
- logger
24+
- matrix-identity-server
25+
- matrix-resolve
26+
- tom-server
27+
- utils
28+
- "Not sure / multiple"
29+
validations:
30+
required: true
31+
32+
- type: input
33+
id: version
34+
attributes:
35+
label: Version
36+
description: Output of `npm list` or the package version from `package.json`.
37+
placeholder: "e.g. 1.4.2"
38+
validations:
39+
required: true
40+
41+
- type: textarea
42+
id: description
43+
attributes:
44+
label: Description
45+
description: A clear summary of what is wrong.
46+
validations:
47+
required: true
48+
49+
- type: textarea
50+
id: steps
51+
attributes:
52+
label: Steps to reproduce
53+
description: Exact steps that reliably trigger the bug.
54+
placeholder: |
55+
1. Start the server with config ...
56+
2. Send request POST /...
57+
3. Observe ...
58+
validations:
59+
required: true
60+
61+
- type: textarea
62+
id: expected
63+
attributes:
64+
label: Expected behaviour
65+
description: What should have happened?
66+
validations:
67+
required: true
68+
69+
- type: textarea
70+
id: actual
71+
attributes:
72+
label: Actual behaviour
73+
description: What happened instead? Include error messages, stack traces, or logs.
74+
validations:
75+
required: true
76+
77+
- type: dropdown
78+
id: severity
79+
attributes:
80+
label: Severity
81+
options:
82+
- "severity::critical — entire project cannot be used"
83+
- "severity::major — some important parts cannot be used"
84+
- "severity::moderate — some parts cannot be used"
85+
- "severity::minor — some parts are inconvenient to use"
86+
- "severity::cosmetic — usage is not impacted"
87+
validations:
88+
required: true
89+
90+
- type: textarea
91+
id: context
92+
attributes:
93+
label: Additional context
94+
description: Node.js version, OS, relevant config, links to related issues, etc.
95+
validations:
96+
required: false

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
name: Feature request
2+
description: Propose a new feature or use case.
3+
labels: ["feature"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Before filing: search open and closed issues to avoid duplicates.
9+
Describe the use case first — proposed solutions without a use case will be closed.
10+
11+
- type: dropdown
12+
id: package
13+
attributes:
14+
label: Package
15+
description: Which package would this affect?
16+
options:
17+
- amqp-connector
18+
- common-settings-bridge
19+
- config-parser
20+
- crypto
21+
- db
22+
- federated-identity-service
23+
- logger
24+
- matrix-identity-server
25+
- matrix-resolve
26+
- tom-server
27+
- utils
28+
- "Not sure / multiple"
29+
validations:
30+
required: true
31+
32+
- type: textarea
33+
id: use_case
34+
attributes:
35+
label: Use case
36+
description: |
37+
What are you trying to do and why can't you do it today?
38+
Start with the problem, not the solution.
39+
placeholder: "As a ... I need to ... because ..."
40+
validations:
41+
required: true
42+
43+
- type: textarea
44+
id: proposal
45+
attributes:
46+
label: Proposed solution
47+
description: |
48+
How do you think this should be solved? API shape, config options, behaviour details.
49+
If you're not sure, leave this blank and let the discussion shape it.
50+
validations:
51+
required: false
52+
53+
- type: textarea
54+
id: alternatives
55+
attributes:
56+
label: Alternatives considered
57+
description: What other approaches did you consider, and why did you rule them out?
58+
validations:
59+
required: false
60+
61+
- type: textarea
62+
id: context
63+
attributes:
64+
label: Additional context
65+
description: Links to related issues, prior art, external specs, etc.
66+
validations:
67+
required: false

‎.github/actions/build-affected/action.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Build
2+
description: Build packages and upload artifacts
3+
4+
inputs:
5+
skip-nx-cache:
6+
description: "Skip nx cache when building"
7+
required: false
8+
default: "false"
9+
upload-artifacts:
10+
description: Whether to upload dist artifacts
11+
default: "false"
12+
13+
runs:
14+
using: composite
15+
steps:
16+
- name: Build all packages
17+
run: npx nx affected -t build ${{ inputs.skip-nx-cache == 'true' && '--skip-nx-cache' || '' }}
18+
shell: bash
19+
20+
- name: Upload dist artifacts
21+
if: inputs.upload-artifacts == 'true'
22+
uses: actions/upload-artifact@v4
23+
with:
24+
name: dist-artifacts-${{ github.run_id }}
25+
path: |
26+
packages/*/dist
27+
retention-days: 1

‎.github/actions/build/action.yml‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,22 +2,26 @@ name: Build
22
description: Build packages and upload artifacts
33

44
inputs:
5+
skip-nx-cache:
6+
description: "Skip nx cache when building"
7+
required: false
8+
default: "false"
59
upload-artifacts:
610
description: Whether to upload dist artifacts
7-
default: 'false'
11+
default: "false"
812

913
runs:
1014
using: composite
1115
steps:
1216
- name: Build all packages
13-
run: npm run build
17+
run: npx nx run-many -t build ${{ inputs.skip-nx-cache == 'true' && '--skip-nx-cache' || '' }}
1418
shell: bash
1519

1620
- name: Upload dist artifacts
1721
if: inputs.upload-artifacts == 'true'
1822
uses: actions/upload-artifact@v4
1923
with:
20-
name: dist-artifacts
24+
name: dist-artifacts-${{ github.run_id }}
2125
path: |
2226
packages/*/dist
2327
retention-days: 1

‎.github/pull_request_template.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
## What
2+
3+
<!-- A concise description of what this PR changes. One paragraph is enough. -->
4+
5+
## Why
6+
7+
<!-- Why is this change needed? Link the issue it addresses. -->
8+
9+
Closes #
10+
11+
## How
12+
13+
<!-- Non-obvious implementation decisions, trade-offs, or anything a reviewer should know before reading the diff. Skip if the why + diff are self-explanatory. -->
14+
15+
## Checklist
16+
17+
### Code
18+
19+
- [ ] Tests pass (`npm test`)
20+
- [ ] Linter is clean (`npm run check`)
21+
- [ ] No new `any` introduced
22+
- [ ] No dead code or commented-out blocks
23+
- [ ] All other style rules per [CODING_STYLE.md](../CODING_STYLE.md)
24+
25+
### Scope
26+
27+
- [ ] This PR addresses one concern (not a mix of bug fixes, refactors, and features)
28+
- [ ] Cross-module changes are documented in the description
29+
30+
### Documentation
31+
32+
- [ ] Inline comments explain _why_, not _what_
33+
- [ ] Relevant docs updated if behaviour changed
34+
35+
### Tests
36+
37+
- [ ] New behaviour is covered by tests
38+
- [ ] If a new endpoint was added: handler integration test included
39+
- [ ] If a new service method was added: unit test with stubbed repo included
40+
41+
### Git
42+
43+
- [ ] Commits follow [convco / Conventional Commits](https://convco.github.io/)
44+
- [ ] Commits are signed (strongly encouraged — see [CONTRIBUTING.md §6](../CONTRIBUTING.md#6-commits--branches))
45+
- [ ] Branch name follows `<type>/<scope>/<description>` convention

‎.github/workflows/AGENTS.md‎

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,26 +4,28 @@
44
# .github/workflows/
55

66
## Purpose
7+
78
GitHub Actions CI/CD workflow definitions. Uses a reusable workflow pattern where `ci.yml` orchestrates calls to specialized reusable workflows (prefixed with `_`). Covers build validation, testing, linting, security scanning, Docker publishing, documentation deployment, and releases.
89

910
## Key Files
1011

11-
| File | Description |
12-
|------|-------------|
13-
| `ci.yml` | Main CI orchestrator — triggers on PR and push, calls reusable workflows |
14-
| `release.yml` | Release workflow — publishes npm packages and Docker images on tags |
15-
| `security-scheduled.yml` | Scheduled security scan (runs on cron schedule) |
16-
| `_build.yml` | Reusable: runs `npm build` and validates compilation |
17-
| `_test.yml` | Reusable: runs `npm test` with coverage |
18-
| `_test-ci.yml` | Reusable: CI-optimized test run (with caching) |
19-
| `_lint.yml` | Reusable: runs ESLint and Prettier checks |
20-
| `_security.yml` | Reusable: njsscan + dependency audit |
21-
| `_docker-publish.yml` | Reusable: builds and pushes Docker image to registry |
22-
| `_docs.yml` | Reusable: deploys Swagger docs to GitHub Pages |
12+
| File | Description |
13+
| ------------------------ | ------------------------------------------------------------------------ |
14+
| `ci.yml` | Main CI orchestrator — triggers on PR and push, calls reusable workflows |
15+
| `release.yml` | Release workflow — publishes npm packages and Docker images on tags |
16+
| `security-scheduled.yml` | Scheduled security scan (runs on cron schedule) |
17+
| `_build.yml` | Reusable: runs `npm build` and validates compilation |
18+
| `_test.yml` | Reusable: runs `npm test` with coverage |
19+
| `_test-ci.yml` | Reusable: CI-optimized test run (with caching) |
20+
| `_lint.yml` | Reusable: runs Biome checks |
21+
| `_security.yml` | Reusable: njsscan + dependency audit |
22+
| `_docker-publish.yml` | Reusable: builds and pushes Docker image to registry |
23+
| `_docs.yml` | Reusable: deploys Swagger docs to GitHub Pages |
2324

2425
## For AI Agents
2526

2627
### Working In This Directory
28+
2729
- All reusable workflows start with `_` — call them from `ci.yml` via `uses: ./.github/workflows/_xxx.yml`
2830
- Secrets referenced: `NPM_TOKEN`, `DOCKER_USERNAME`, `DOCKER_PASSWORD`, `GITHUB_TOKEN`
2931
- Node.js version is pinned via `.node-version` file at the repo root

‎.github/workflows/_build-affected.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Build
2+
3+
on:
4+
workflow_call:
5+
inputs:
6+
skip-nx-cache:
7+
description: "Skip nx cache when building"
8+
required: false
9+
type: boolean
10+
default: false
11+
upload-artifacts:
12+
type: boolean
13+
default: false
14+
secrets:
15+
NX_CLOUD_ACCESS_TOKEN:
16+
required: false
17+
18+
permissions:
19+
actions: read
20+
contents: read
21+
22+
jobs:
23+
build:
24+
name: Build Affected Packages
25+
runs-on: ubuntu-latest
26+
env:
27+
NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
28+
steps:
29+
- name: Checkout repository
30+
uses: actions/checkout@v4
31+
with:
32+
fetch-depth: 0
33+
34+
- name: Setup Node.js
35+
uses: ./.github/actions/setup-node
36+
37+
- name: Setup Nx SHAs
38+
uses: nrwl/nx-set-shas@v4
39+
40+
- name: Build
41+
uses: ./.github/actions/build-affected
42+
with:
43+
skip-nx-cache: ${{ inputs.skip-nx-cache }}
44+
upload-artifacts: ${{ inputs.upload-artifacts }}

0 commit comments

Comments
 (0)