Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
73 changes: 73 additions & 0 deletions .agents/skills/mcpp-ide-contributing/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
name: mcpp-ide-contributing
description: Use when contributing to mcpp-ide -- reporting a bug, proposing a feature, opening an issue or a pull request, or making any change as a person or an AI agent. Covers triage (core or plugin, fix or workaround), issue and pull-request conventions, commits, review and merge.
---

# Contributing to mcpp-ide

Read [AGENTS.md](../../../AGENTS.md) first: who owns what, and the rules every change follows. The
flow is **issue → branch → pull request → CI → review → squash merge**. Nothing is pushed to `main`
directly, whatever its size, and that includes a version bump or a change to documentation.

## 1. Triage before anything else

Answer the three questions of AGENTS.md §3 and write the answers into the issue:

| Question | How to decide | Outcome |
|---|---|---|
| Whose problem? | reproduce without the editor: `mcpp-ide self-check --json`, `mcpp-ide serve`, the mock mcpp | mcpp, mcppls or an editor's upstream: report it there and link it here |
| Core or plugin? | would another editor need the same change? | yes → backend (`src/`, `spec/`, `protocol/`); no → `mide-plugins/<editor>` |
| Fix or workaround? | does the cause lie in this repository? | no → no workaround by default; an exception states its cause, the upstream issue, why it cannot wait and when it is removed |

## 2. Issues

Open one with a template (`.github/ISSUE_TEMPLATE/`): **Bug report**, **Feature request** or
**Task**. A blank issue is not offered, and a question goes to the
[forum](https://forum.d2learn.org/category/20).

- Title: `<type>(<component>): <sentence>`, for example `fix(clion): the test tree loses a case's
location after a rebuild`. The type is one of `feat`, `fix`, `refactor`, `perf`, `test`, `docs`,
`ci`, `chore`. The component is `backend`, `vscode`, `clion`, `nvim`, `docs` or `ci`.
- A bug carries the output of `mcpp-ide self-check --json` (backend, mcpp, mcppls, xlings, trust),
the editor and its version, the steps, the expected and actual behaviour, and the triage answers.
The IDE report (**mcpp: Export IDE Report**) is attached when the backend is involved.
- A feature states the motivation, which party it belongs to, the protocol or `spec/` change it
needs, and what each editor shows. A change larger than one pull request gets a design record in
`.agents/docs/` (`YYYY-MM-DD-<subject>.md`, opening with its status) before any code.

## 3. Branches and commits

- Branch from the latest `main`: `<type>/<subject>`, for example `fix/clion-case-location`. A
release is made on `release/X.Y.Z` (see [mcpp-ide-development](../mcpp-ide-development/SKILL.md)).
- A commit is English and declarative, `<type>(<component>): <sentence>` or `X.Y.Z: <sentence>` for
a release, with no emoji. Its body says why, citing the issue, the design record or mcpp's spec
clause where there is one.

## 4. Pull requests

- One pull request does one thing and links the issue it closes (`Closes #N`). The title follows
the commit form, since it becomes the subject of the squash merge.
- The body follows `.github/pull_request_template.md`: summary, triage, the criteria (the test that
fails before and passes after, and where it ran), compatibility and the checklist.
- A change of behaviour updates, in the same pull request: `protocol/protocol.schema.json`, the docs
it touches (README.md and README.zh-CN.md together), `spec/i18n` in both languages, and
CHANGELOG.md under its series.
- The required check is `ci`. It runs the components the change reaches (`.github/components.tsv`),
so a backend change runs every plugin. A red job is fixed, never retried until green.
- The merge is a squash with an explicit subject and body; GitHub's composed message is not used.

## 5. AI agents

An agent contributes under the same rules, plus these:

- **Read before writing:** AGENTS.md, the docs it links for the area, and the neighbouring code. Do
the triage before editing, and say in the pull request which party the problem belongs to.
- **Ask before outward actions:** creating an issue, a pull request, a comment, a tag or a release
needs the person's confirmation. Never push to `main`, force-push a shared branch, merge, tag or
publish unless explicitly asked.
- **Report what ran:** each criterion says whether it ran locally, on which system, or was left to
CI. A test that did not run is not described as passing.
- **Stay in scope:** no drive-by refactors, no new dependency and no workaround for another party's
problem without the person's decision.
- **No attribution trailers:** commits and pull requests carry no `Co-Authored-By` lines or
generated-by footers. The person who submits a change is responsible for it.
77 changes: 77 additions & 0 deletions .agents/skills/mcpp-ide-development/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
---
name: mcpp-ide-development
description: Use when setting up a development environment for mcpp-ide, building or testing the backend or an editor plugin, changing the protocol, spec/, fixtures or strings, bumping a pinned tool, or preparing a release (a series vX.Y.0 or a plugin patch).
---

# Developing mcpp-ide

## 1. Environment

The pins live in [.github/versions.env](../../../.github/versions.env), which CI reads. A local
setup uses the same versions:

| Tool | Version | For | Install |
|---|---|---|---|
| xlings | `XLINGS_VERSION` | mcpp, toolchains, gradle | [xlings](https://github.com/d2learn/xlings) |
| mcpp | `.xlings.json` (= `MCPP_VERSION`) | the backend; its toolchain comes from `mcpp.toml` | `xlings install` in the repository |
| Node.js | 22 | the VS Code extension, the web UI tests | any Node 22 |
| VS Code | `VSCODE_VERSION` (the oldest supported) | the extension's e2e tests | fetched by `@vscode/test-electron` |
| Gradle and its JDK | xlings's | the CLion plugin | `xlings install gradle` |
| Neovim | 0.10+ | the Neovim plugin | system package |

Check the environment with `mcpp build && mcpp run mcpp-ide -- self-check`.

## 2. Build and test, per component

Run what a change reaches ([.github/components.tsv](../../../.github/components.tsv)). A backend
change reaches every plugin, because each plugin is tested over the backend.

| Component | Paths | Commands |
|---|---|---|
| backend | `src/`, `protocol/`, `spec/`, `webui/`, `tests/`, `testsupport/`, `mcpp.toml` | `mcpp build`, `mcpp test`, `mcpp run mcpp-ide-dev -- check-sources`, `mcpp run mcpp-ide-dev -- check-i18n` |
| vscode | `mide-plugins/vscode/` | `npm ci && npm test`; `npm run test:parity`, `npm run test:webui`, `npm run test:e2e`; `npm run package` |
| clion | `mide-plugins/clion/` | `gradle test buildPlugin verifyPlugin` |
| nvim | `mide-plugins/nvim/` | `nvim --headless --clean -l mide-plugins/nvim/tests/smoke.lua` |
| CI | `.github/` | `bash .github/scripts/test_changes.sh`, `bash .github/scripts/release-plan.sh` |

## 3. Common changes

- **A protocol method or notification:** change `protocol/protocol.schema.json` together with the
backend and every plugin that uses it. The backend's tests check its answers against the schema.
- **A setting, command or editor string:** edit `spec/` (`settings.json`, `commands.json`,
`i18n/*.json`), then run `mcpp run mcpp-ide-dev -- gen vscode` and commit what it rewrites in
`mide-plugins/vscode`. CLion's declarations are generated at build time. Neovim reads the table at
run time. A command that an editor does not offer states why (`omitted`).
- **A runtime string:** pass it through `t(...)` and add its Chinese entry to
`spec/i18n/runtime.zh-cn.json`; `check-i18n` enforces this.
- **What mcpp reports:** run `mcpp run mcpp-ide-dev -- capture` against a real mcpp and review the
diff in `protocol/fixtures`. Update `protocol/mcpp-contract.schema.json` if the contract grew.
The mock mcpp and every plugin's tests replay these fixtures.
- **A feature of a newer mcpp or mcppls:** enable it from what mcpp states (`features`). An earlier
release is described by a table frozen at that release, not by comparing versions.
- **A pinned tool:** change `.github/versions.env`, `.xlings.json` and `mcpp = ">=..."` in
`mcpp.toml` together, and only to versions that are already released and indexed.

## 4. Diagnosing

- `mcpp-ide self-check --json` reports the backend, mcpp and its contract, mcppls, xlings and trust.
- The IDE report (**mcpp: Export IDE Report**, `:Mcpp exportReport`) collects the projects' mcpp,
mcppls's status, the settings in effect, recent jobs and the backend's log.
- `mcpp.backend.logLevel` controls how much the backend writes to the editor's log.

## 5. Release

The rules are in AGENTS.md §4 and [release-plan.sh](../../../.github/scripts/release-plan.sh).

1. Decide the kind. Any backend path changed since `vX.Y.0` means a series release `vX.Y+1.0` (or
`vX+1.0.0`). Otherwise it is a plugin patch, `<vscode|clion|nvim>-vX.Y.Z+1`.
2. On `release/<version>`, bump the version statements (all six for a series, only the plugin's
own for a patch) and add the CHANGELOG.md section under its series, listing each component's
version. Then run `bash .github/scripts/release-plan.sh <tag>`.
3. Open a pull request titled `X.Y.Z: <sentence>` and merge it after `ci` passes.
4. Tag the merge commit and push the tag. `release.yml` runs CI, publishes the GitHub release with
`SHA256SUMS`, then submits the same VSIX to Open VSX and the same ZIP to JetBrains Marketplace.
The Visual Studio Marketplace upload is manual. The secrets are `OPENVSX_TOKEN` and
`JETBRAINS_TOKEN`; Marketplace availability follows JetBrains review.
5. Watch the run until every job passes, then check that the release assets install
(`mcpp-ide self-check` on a project).
64 changes: 64 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
name: Bug report
description: mcpp-ide or one of its editor plugins behaves wrongly
title: "fix(<component>): "
labels: [bug]
body:
- type: markdown
attributes:
value: |
Triage first ([AGENTS.md §3](https://github.com/mcpp-community/mcpp-ide/blob/main/AGENTS.md)):
reproduce without the editor where you can, and report problems of mcpp or mcppls in their own repositories.
- type: dropdown
id: component
attributes:
label: Component
options: [backend, vscode, clion, nvim, packaging / install, docs]
validations:
required: true
- type: textarea
id: steps
attributes:
label: Steps to reproduce
description: The smallest project and the actions that show the problem.
placeholder: |
1. mcpp new demo && cd demo
2. ...
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected and actual behaviour
validations:
required: true
- type: textarea
id: selfcheck
attributes:
label: mcpp-ide self-check --json
description: The backend, mcpp and its contract, mcppls, xlings and trust.
render: json
validations:
required: true
- type: input
id: editor
attributes:
label: Editor and OS
placeholder: VS Code 1.95 / CLion 2026.1 / Neovim 0.11 on Ubuntu 24.04 x86_64
validations:
required: true
- type: dropdown
id: party
attributes:
label: Whose problem is it?
description: Where does it still reproduce once the editor is taken away?
options:
- The backend (every editor shows it)
- One editor plugin only
- Not sure yet
validations:
required: true
- type: textarea
id: logs
attributes:
label: Logs or IDE report
description: "mcpp: Export IDE Report (Neovim :Mcpp exportReport), or the backend's log."
11 changes: 11 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
blank_issues_enabled: false
contact_links:
- name: Question or discussion
url: https://forum.d2learn.org/category/20
about: Usage questions and ideas go to the community forum.
- name: A problem of mcpp itself
url: https://github.com/mcpp-community/mcpp/issues/new/choose
about: Wrong output from mcpp (builds, tests, the machine contract) is reported to mcpp.
- name: A C++ language feature (mcppls)
url: https://github.com/Sunrisepeak/mcpp-language-server/issues
about: Completion, navigation and diagnostics of C++ files come from mcppls.
34 changes: 34 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
name: Feature request
description: A new capability or a change of behaviour
title: "feat(<component>): "
labels: [enhancement]
body:
- type: textarea
id: motivation
attributes:
label: Motivation
description: The problem it solves, and for whom.
validations:
required: true
- type: dropdown
id: party
attributes:
label: Where does it belong?
description: A decision every editor shares belongs to the backend; plugins only map it onto their UI.
options:
- Backend (protocol / spec), shown by every editor
- One editor plugin's presentation
- Needs mcpp or mcppls to state something new first
validations:
required: true
- type: textarea
id: design
attributes:
label: Design
description: The protocol or spec/ change, what each editor shows, and the mcpp feature it relies on. A change larger than one pull request starts with a record in .agents/docs/.
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives considered
22 changes: 22 additions & 0 deletions .github/ISSUE_TEMPLATE/task.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
name: Task
description: Maintenance, refactoring, CI, documentation or a release
labels: [task]
body:
- type: dropdown
id: type
attributes:
label: Type
options: [refactor, perf, test, docs, ci, chore, release]
validations:
required: true
- type: textarea
id: what
attributes:
label: What and why
validations:
required: true
- type: textarea
id: done
attributes:
label: Done when
description: The criteria that close this task.
3 changes: 3 additions & 0 deletions .github/components.tsv
Original file line number Diff line number Diff line change
Expand Up @@ -25,5 +25,8 @@ docs docs/*
docs agents/*
docs *.md
docs LICENSE
# The forms of issues and pull requests are read by people too, although they live under .github/.
docs .github/ISSUE_TEMPLATE/*
docs .github/pull_request_template.md
# The workflows, the scripts and the pins every job runs with.
all .github/*
26 changes: 26 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
## Summary

<!-- What changes and why, in declarative sentences. Closes #N. -->

## Triage

<!-- AGENTS.md §3: which party owns the problem (mcpp, mcppls, backend or one plugin)?
A workaround for another party's problem states its cause, the upstream issue,
why it cannot wait and when it is removed. Write "n/a" for a pure refactor. -->

## Criteria

<!-- For each change: the test that fails before and passes after, and where it ran
(local system or CI job). A criterion left to CI says so. -->

## Compatibility

<!-- What a user or a client observes after the upgrade: a protocol change, a changed
setting or default, a migration, the oldest mcpp or editor still supported. -->

## Checklist

- [ ] One thing; the title is `<type>(<component>): <sentence>` (or `X.Y.Z: <sentence>`).
- [ ] The protocol schema, docs (README in both languages), `spec/i18n` and CHANGELOG.md follow the behaviour.
- [ ] `spec/` is edited, not its output; `mcpp-ide-dev gen vscode` leaves no diff.
- [ ] No commit carries an attribution trailer (`git log origin/main..HEAD -i --grep=Co-Authored-By` is empty).
2 changes: 2 additions & 0 deletions .github/scripts/test_changes.sh
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ check "its README is the plugin's" pull_request vscode=true docs=false backend=f
check "documentation alone" pull_request docs=true backend=false vscode=false -- docs/x.md README.md
check "the backend reaches every plugin" pull_request backend=true vscode=true clion=true nvim=true -- src/main.cpp
check "spec/ is the backend's" pull_request backend=true vscode=true -- spec/test-frameworks.json
check "the issue and pull-request forms are documentation" pull_request docs=true backend=false full=false -- .github/ISSUE_TEMPLATE/bug_report.yml .github/pull_request_template.md
check "a skill is documentation" pull_request docs=true backend=false full=false -- .agents/skills/mcpp-ide-development/SKILL.md AGENTS.md
check "a workflow reaches everything" pull_request full=true backend=true -- .github/workflows/ci.yml
check "a path of no component reaches everything" pull_request full=true -- newdir/x
check "a push reaches everything" push full=true backend=true -- docs/x.md
Expand Down
Loading
Loading