Skip to content

Fix/docs and ci #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Lambdius merged 3 commits into from
Oct 20, 2026
Merged

Fix/docs and ci #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3e9e6d2
fix(docs): isolate Scalar configuration
Lambdius Oct 19, 2026
3ccdb5e
fix: preserve OAuth popup communication & pin CodeQL actions
Lambdius Oct 20, 2026
efacc4b
docs: reorganize README and CONTRIBUTING, add RU versions
Lambdius Oct 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/workflows/codeql.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ jobs:
# your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
steps:
- name: Checkout repository
uses: actions/checkout@v7
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

# Add any setup steps before running the `github/codeql-action/init` action.
# This includes steps like installing compilers or runtimes (`actions/setup-node`
Expand All @@ -66,7 +66,7 @@ jobs:

# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
uses: github/codeql-action/init@v4
uses: github/codeql-action/init@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
with:
languages: ${{ matrix.language }}
build-mode: ${{ matrix.build-mode }}
Expand Down Expand Up @@ -95,6 +95,6 @@ jobs:
exit 1

- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v4
uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
with:
category: "/language:${{matrix.language}}"
172 changes: 129 additions & 43 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,33 @@
# Contributing

Language: **EN** | [RU](CONTRIBUTING.ru.md)

----

<details>
<summary><strong>Environment Setup</strong></summary>

> The application requires `Node.js v24.18.0` and the pnpm version pinned in `package.json`;
> other versions are not supported.
> The application requires the Node.js and pnpm versions specified in `package.json`.
> Other versions are not supported.

> The git hooks additionally require [`jq`](https://jqlang.github.io/jq/download/)
> and [`gitleaks`](https://github.com/gitleaks/gitleaks#installing) to be available
> in `PATH`; a commit is rejected when either of them is missing.
> Git hooks require [`jq`](https://jqlang.github.io/jq/download/)
> and [`gitleaks`](https://github.com/gitleaks/gitleaks#installing).
> A commit is rejected if either tool is missing.

> Pre-commit also runs the complete unit and integration suites. Docker must be
> running and accessible to the current user. Testcontainers starts isolated
> PostgreSQL, Redis, Kafka and Schema Registry containers; the application stack
> and a local `.env` are not required. The first run downloads container images.

Project commands: [README](README.md).

[VSCode](https://code.visualstudio.com/) is the recommended editor for development.

#### VSCode Setup
Install the following extensions for proper [ESLint](https://eslint.org/docs/latest/), [Prettier](https://prettier.io/docs/en/), and [EditorConfig](https://editorconfig.org/) integration:

Install the following extensions for proper [ESLint](https://eslint.org/docs/latest/),
[Prettier](https://prettier.io/docs/en/), and [EditorConfig](https://editorconfig.org/) integration:

1. `dbaeumer.vscode-eslint`
2. `rvest.vs-code-prettier-eslint`
3. `esbenp.prettier-vscode`
Expand All @@ -33,68 +40,147 @@ Install the following extensions for proper [ESLint](https://eslint.org/docs/lat
<details>
<summary><strong>Git Hooks</strong></summary>

*Enable git hooks:*
Enable Git hooks:
```sh
chmod +x .githooks/*
git config core.hooksPath .githooks
```

#### Checks executed on commit:
#### Pre-commit Checks

`pre-commit` runs the steps below in order and stops at the first failure:
1. `Secret scan` — Gitleaks on staged changes.
2. `Environment` — environment configuration consistency.
3. `Translations` — dictionary consistency, see `scripts/intl.check.sh`.
4. `Type check` — TypeScript check of the whole project.
5. `Unused code` — unused exports, files, and dependencies.
6. `Lint` — ESLint on the whole project, using the same script as CI.
7. `Unit tests` — the complete unit suite in Jest CI mode.
8. `Integration tests` — the complete integration suite in Jest CI mode.

1. `Secret scan` — Gitleaks on staged changes.
2. `Environment` — environment configuration consistency.
3. `Translations` — dictionary consistency, see `scripts/intl.check.sh`.
4. `Type check` — TypeScript check of the whole project.
5. `Unused code` — unused exports, files, and dependencies.
6. `Lint` — ESLint on the whole project, using the same script as CI.
7. `Unit tests` — the complete unit suite in Jest CI mode.
8. `Integration tests` — the complete integration suite in Jest CI mode.

The hook rejects the commit if Docker is unavailable or a test fails. Checks run
against the working tree, including unstaged changes. CI checks PR to `dev`.

#### Allowed prefixes for commits and branches:
#### Allowed Commit and Branch Prefixes

`feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.

#### Commit message format:
#### Commit Message Format

```text
<type>(<scope>)?[!]: <subject>
```

*Where:*
- `<type>` — one of the allowed prefixes above.
- `<scope>` — optional scope in parentheses, alphanumeric/`-`.
- `!` — optional breaking change marker.
- `: ` — colon + space are required.
- `<subject>` — short description.
> Total commit message length is limited to 70 characters.

*Valid commit examples:*
- `feat: add filters to user search`
- `fix(auth): handle invalid jwt token`
- `refactor(user-service)!: drop legacy ws implementation`
- `docs: update api usage section`
- `chore(ci): tweak lint step`

#### Branch naming format:
- `<type>` — one of the allowed prefixes above.
- `<scope>` — optional scope in parentheses, alphanumeric/`-`.
- `!` — optional breaking change marker.
- `: ` — colon + space are required.
- `<subject>` — short description.

> The commit subject line is limited to 70 characters.

Examples:

- `feat: add filters to user search`
- `fix(auth): handle invalid jwt token`
- `refactor(user-service)!: drop legacy ws implementation`
- `docs: update api usage section`
- `chore(ci): tweak lint step`

#### Branch Naming Format

```text
<type>/<slug>
<type>/<scope-or-id>/<slug>
```

*Where:*
- `<type>` — one of the prefixes listed above.
- `/<scope-or-id>` — optional part, alphanumeric/`-`.
- `/<slug>` — short description, alphanumeric/`_`/`-`.
- `<type>` — one of the prefixes listed above.
- `/<scope-or-id>` — optional part, alphanumeric/`-`.
- `/<slug>` — short description, alphanumeric/`_`/`-`.

Examples:

*Valid branch examples:*
- `feat/add-user-search-filters`
- `fix/schedule-update-ws-event`
- `refactor/core-user-cleanup`
- `feat/GOTEC-404/add-notifications-for-users`
- `feat/add-user-search-filters`
- `fix/schedule-update-ws-event`
- `refactor/core-user-cleanup`
- `feat/GOTEC-404/add-notifications-for-users`

> Exceptions: `dev`, `main`, `master`.

</details>

----

<details>
<summary><strong>Releasing a new version</strong></summary>

1. Create a branch and update `version` in `package.json`. The example below uses `1.0.0`:
```bash
git switch dev
git pull --ff-only
git switch -c chore/release-v1.0.0
# Update the version in package.json before committing.
git add package.json
git commit -m "chore: release v1.0.0"
git push -u origin chore/release-v1.0.0
```

2. Open a PR into `dev`, pass CI, merge and wait for **Publish service image** to succeed.

3. Tag the published commit; the tag must match `package.json`:
```bash
git switch dev
git pull --ff-only
git tag v1.0.0
git push origin v1.0.0
```

</details>

----

> The following tools are experimental and optional. They help LLM agents
> navigate code and component relationships in a local checkout.
> They are not required to develop or run the service.

----

<details>
<summary><strong>Local Code Graph (Graphify)</strong></summary>

Install once with [uv](https://docs.astral.sh/uv/), then open a new terminal:

```sh
uv tool install graphifyy==0.9.65
uv tool update-shell
```

Run `make graphify` from the repository root to create or update the local code
graph and report. No API key is required. Outputs in `graphify-out/` are ignored
by Git. Agent guidance: [AGENTS.md](AGENTS.md).

</details>

----

<details>
<summary><strong>Local TypeScript Navigation (LSP-MCP)</strong></summary>

[lsmcp](https://github.com/mizchi/lsmcp) and TypeScript Language Server are pinned
dev dependencies. Run `make lsp` from the repository root to start the MCP server
over stdio; an MCP client is required to send queries.

For an MCP client, use command `node`, arguments
`["node_modules/@mizchi/lsmcp/dist/lsmcp.js", "--config", ".lsmcp/config.json"]`,
and set its working directory to this repository. Desktop clients may need an
absolute Node executable path. Configuration: [.lsmcp/config.json](.lsmcp/config.json).
Local indexes and caches are ignored by Git. Agent guidance: [AGENTS.md](AGENTS.md).

Known limitation in lsmcp 0.10.0: definition previews can be empty for encoded
pnpm dependency paths. Hover still works; `resolve_symbol` locates the installed
package entry point. See [AGENTS.md](AGENTS.md) for the fallback.

</details>

----
Loading
Loading