You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by po...@apache.org on 2026/07/05 18:24:18 UTC
(magpie) branch main updated: docs(bitbucket): clarify partial bridge coverage (#748)
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/magpie.git
The following commit(s) were added to refs/heads/main by this push:
new 12b3868b docs(bitbucket): clarify partial bridge coverage (#748)
12b3868b is described below
commit 12b3868badc98d3abbf725c70047510f138fffb7
Author: Kavya Katal <KA...@GMAIL.COM>
AuthorDate: Sun Jul 5 23:54:12 2026 +0530
docs(bitbucket): clarify partial bridge coverage (#748)
---
docs/adapters/registry.md | 2 +-
docs/labels-and-capabilities.md | 13 ++++++++++++-
docs/vendor-neutrality.md | 9 +++++----
tools/bitbucket/README.md | 41 +++++++++++++++++++++++++++++++++++------
4 files changed, 53 insertions(+), 12 deletions(-)
diff --git a/docs/adapters/registry.md b/docs/adapters/registry.md
index 992b87e3..1fc85351 100644
--- a/docs/adapters/registry.md
+++ b/docs/adapters/registry.md
@@ -51,7 +51,7 @@ extension point = a documented, labelled slot with a tracking issue.
| [`tools/forwarder-relay`](../../tools/forwarder-relay/) | ASF-security ([`tools/gmail/asf-relay.md`](../../tools/gmail/asf-relay.md)) | huntr.com, HackerOne, GHSA relay |
| [`tools/scan-format`](../../tools/scan-format/) | ASVS | other scanner formats |
| [`tools/vcs`](../../tools/vcs/) | Git, Mercurial, Fossil | Subversion [\#602](https://github.com/apache/magpie/issues/602), Jujutsu [\#603](https://github.com/apache/magpie/issues/603), Perforce [\#605](https://github.com/apache/magpie/issues/605) |
-| Forge / tracker | [`github`](../../tools/github/), [`jira`](../../tools/jira/), [`bitbucket`](../../tools/bitbucket/) read-only foundation, [`sourcehut`](../../tools/sourcehut/), [`fossil`](../../tools/fossil/) | GitLab [\#305](https://github.com/apache/magpie/issues/305), Forgejo/Gitea [\#310](https://github.com/apache/magpie/issues/310), Pagure [\#312](https://github.com/apache/magpie/issues/312), deeper Bitbucket/Jira coverage [\#606](https://github.com/apache/magpie/issues/606), Bu [...]
+| Forge / tracker | [`github`](../../tools/github/), [`jira`](../../tools/jira/), [`bitbucket`](../../tools/bitbucket/) `partial-read-only` foundation, [`sourcehut`](../../tools/sourcehut/), [`fossil`](../../tools/fossil/) | GitLab [\#305](https://github.com/apache/magpie/issues/305), Forgejo/Gitea [\#310](https://github.com/apache/magpie/issues/310), Pagure [\#312](https://github.com/apache/magpie/issues/312), deeper Bitbucket/Jira coverage [\#606](https://github.com/apache/magpie/issue [...]
| Agentic runtime | Claude Code | Codex [#313](https://github.com/apache/magpie/issues/313)–OpenHands [#322](https://github.com/apache/magpie/issues/322) |
| Security cross-ref | — | OSV.dev [#311](https://github.com/apache/magpie/issues/311) |
diff --git a/docs/labels-and-capabilities.md b/docs/labels-and-capabilities.md
index d8394720..3f7e63a4 100644
--- a/docs/labels-and-capabilities.md
+++ b/docs/labels-and-capabilities.md
@@ -6,6 +6,7 @@
- [Label dimensions](#label-dimensions)
- [1. `family:*` — subject](#1-family--subject)
- [2. capability — two axes (skills vs tools)](#2-capability--two-axes-skills-vs-tools)
+ - [Coverage qualifiers](#coverage-qualifiers)
- [3. `kind:*` — change type (pre-existing)](#3-kind--change-type-pre-existing)
- [4. `mode:*` — handling mode (pre-existing)](#4-mode--handling-mode-pre-existing)
- [Standalone labels](#standalone-labels)
@@ -100,6 +101,7 @@ framework substrate:
| `contract:tracker` | contract | Issue / board / label backend. |
| `contract:source-control` | contract | Branch / commit / diff / push (VCS). |
| `contract:change-request` | contract | Proposed-change review + merge gate (pull request / merge request / Gerrit change). |
+
| `contract:mail-archive` | contract | Mailing-list / forum archive reads. |
| `contract:mail-source` | contract | Inbound-mail ingestion (mbox / IMAP / …). |
| `contract:mail-create` | contract | Outbound mail composition. Always produces an editable draft; sending is a separate human-approved step on that draft (draft mode = default and the only mode implemented today; send mode declared but unimplemented — no autonomous send). |
@@ -113,6 +115,15 @@ framework substrate:
| `substrate:privacy` | substrate | PII redaction / approved-LLM gating. |
| `substrate:framework-dev` | substrate | Build / validate / eval the framework itself. |
+### Coverage qualifiers
+
+Some tool READMEs may declare a `Coverage:` qualifier next to a capability
+when the tool intentionally implements only part of a contract.
+
+`partial-read-only` means the tool implements a read-only subset of named
+contract operations, but does not satisfy the complete contract and must not
+be advertised as a complete/selectable backend.
+
Both capability axes are **orthogonal** to `family:*`. A single
query can answer "how is our triage stack doing across PR + issue +
security?" by filtering on `capability:triage` alone, without
@@ -258,7 +269,7 @@ it implements multiple contracts (e.g. `tools/gmail` provides both
| [`tools/dev`](../tools/dev/) | `substrate:framework-dev` | Framework dev-loop helpers |
| [`tools/egress-gateway`](../tools/egress-gateway/) | `substrate:sandbox` | Egress-allowlist forward proxy (proxy.py plugin); host-level egress chokepoint — defence-in-depth for RFC-AI-0003 §4.4 |
| [`tools/forwarder-relay`](../tools/forwarder-relay/) | `contract:report-relay` | Adapter contract for inbound-relay backends (ASF Security relay, huntr.com, HackerOne triagers). Pure interface spec; adapters declare detection + credit-extraction + reporter-addressing rules. |
-| [`tools/bitbucket`](../tools/bitbucket/) | `contract:change-request` | Bitbucket Cloud and Bitbucket Data Center read-only bridge foundation for repository metadata and pull-request discovery/fetching. Future PRs will add Bitbucket Issues / Jira handoff coverage before claiming tracker completeness. |
+| [`tools/bitbucket`](../tools/bitbucket/) | `contract:change-request` | Coverage: `partial-read-only`. Bitbucket Cloud and Bitbucket Data Center bridge foundation for repository metadata context and pull-request discovery/fetching. The `partial-read-only` qualifier means this tool implements named read-only contract operations but does not satisfy the complete contract and must not be counted as a complete/selectable backend. `contract:tracker` remains absent until Bitbucket issue opera [...]
| [`tools/fossil`](../tools/fossil/) | `contract:tracker` + `contract:source-control` | Fossil SCM forge bridge: integrates local SQLite-backed ticket tracking, wiki, and forum reads with the version-control shim |
| [`tools/github`](../tools/github/) | `contract:tracker` + `contract:source-control` + `contract:change-request` | GitHub REST / GraphQL tracker substrate (called by every lifecycle phase) plus the Git source-control binding documented in [`source-control.md`](../tools/github/source-control.md) (runnable backend in [`tools/vcs`](../tools/vcs/)) and the pull-request review/merge gate (`change-request`; the ASF default backend, alongside `tools/jira-patch/` and `tools/mail-patch/` for SVN [...]
| [`tools/github-body-field`](../tools/github-body-field/) | `contract:tracker` | Read or rewrite one `### Field` section of a GitHub issue body without bringing the body into agent context — substrate helper for the security-sync skills |
diff --git a/docs/vendor-neutrality.md b/docs/vendor-neutrality.md
index 84a66bf3..048bcf16 100644
--- a/docs/vendor-neutrality.md
+++ b/docs/vendor-neutrality.md
@@ -348,8 +348,9 @@ issue`, not hypothetical:
[Pagure](https://github.com/apache/magpie/issues/312) (Fedora /
`pagure.io`),
[Bitbucket](https://github.com/apache/magpie/issues/606) (initial
-[`tools/bitbucket`](../tools/bitbucket/) bridge; deeper Jira pairing and
-write coverage tracked there), and
+[`tools/bitbucket`](../tools/bitbucket/) `partial-read-only` bridge;
+deeper Jira pairing, complete change-request coverage, and write
+coverage tracked there), and
[SourceHut](https://github.com/apache/magpie/issues/607) (email-patch
review). Tracker-only surfaces are tracked the same way — e.g.
[Bugzilla](https://github.com/apache/magpie/issues/302) — alongside the
@@ -423,7 +424,7 @@ binding; `tools/asf-svn` covers the full ASF SVN surface including
[Fossil](https://github.com/apache/magpie/issues/604), and
[Perforce](https://github.com/apache/magpie/issues/605) — so the
extension points are public and labelled, not hypothetical. (The
-Bitbucket and SourceHut forges, which carry their own VCS, are tracked
+Bitbucket and SourceHut forges, which carry their own VCS surfaces, are tracked
under the forge axis above.)
### 6. Project governance
@@ -487,7 +488,7 @@ coverage without pretending one team can implement an open-ended set.
|---|---|---|---|
| LLM backend | ✅ by construction | Claude Code, Ollama, vLLM, Apache-hosted, Bedrock, direct Anthropic | Any endpoint meeting the capability floor + privacy gate |
| Agentic runtime | ✅ by construction (`AGENTS.md` standard) | Claude Code; community use under Codex, Cursor, Gemini CLI, Copilot, OpenCode, Kiro | Runtime adapters [#313–#322](https://github.com/apache/magpie/issues?q=is%3Aissue+state%3Aopen+adapter+in%3Atitle) |
-| Forge / tracker | ✅ by construction | GitHub, Jira, SourceHut; Bitbucket read-only foundation; CVE/scan/relay via adapter contracts | GitLab [#305](https://github.com/apache/magpie/issues/305), Forgejo/Gitea [#310](https://github.com/apache/magpie/issues/310), Pagure [#312](https://github.com/apache/magpie/issues/312), full Bitbucket tracker/change-request/Jira coverage [#606](https://github.com/apache/magpie/issues/606), Bugzilla [#302](https://github.com/apache/magpie/issues/302) |
+| Forge / tracker | ✅ by construction | GitHub, Jira, SourceHut; Bitbucket `partial-read-only` foundation excluded from complete-backend counts; CVE/scan/relay via adapter contracts | GitLab [#305](https://github.com/apache/magpie/issues/305), Forgejo/Gitea [#310](https://github.com/apache/magpie/issues/310), Pagure [#312](https://github.com/apache/magpie/issues/312), full Bitbucket tracker/change-request/Jira coverage [#606](https://github.com/apache/magpie/issues/606), Bugzilla [#302]( [...]
| Communication channels | ✅ by construction | PonyMail / mail-archive reads | mbox [#304](https://github.com/apache/magpie/issues/304), IMAP [#303](https://github.com/apache/magpie/issues/303), Mailman 3 [#306](https://github.com/apache/magpie/issues/306); Discourse [#307](https://github.com/apache/magpie/issues/307), Zulip [#308](https://github.com/apache/magpie/issues/308), Matrix [#309](https://github.com/apache/magpie/issues/309) |
| Source control (VCS) | ✅ by construction | **Git (complete)**, **Mercurial (complete)**; ASF SVN surface ([`tools/asf-svn`](../tools/asf-svn/): source control + dist.apache.org + authorization) | Subversion generic VCS binding [\#602](https://github.com/apache/magpie/issues/602) (detected); Jujutsu [\#603](https://github.com/apache/magpie/issues/603), Fossil [\#604](https://github.com/apache/magpie/issues/604), Perforce [\#605](https://github.com/apache/magpie/issues/605) (tracked) |
| Project governance | ✅ by construction | ASF + non-ASF adopter profiles | Adopter config (modes, thresholds) |
diff --git a/tools/bitbucket/README.md b/tools/bitbucket/README.md
index 24c0c382..81a0d5d6 100644
--- a/tools/bitbucket/README.md
+++ b/tools/bitbucket/README.md
@@ -5,6 +5,7 @@
- [Bitbucket forge bridge](#bitbucket-forge-bridge)
- [Prerequisites](#prerequisites)
- [Features](#features)
+ - [Operation coverage](#operation-coverage)
- [Invocation](#invocation)
- [Configuration](#configuration)
- [Output contract](#output-contract)
@@ -20,6 +21,8 @@
**Capability:** contract:change-request
+**Coverage:** `partial-read-only`
+
**Kind:** implementation
**Vendor:** Atlassian
@@ -27,12 +30,20 @@
Bitbucket Cloud and Bitbucket Data Center bridge for Magpie adopters
that use Bitbucket as a forge, pull-request review surface, or Jira-paired Atlassian backend.
-This initial bridge provides a read-only foundation for repository
-metadata and pull-request discovery/fetching. It is not a complete
-`contract:change-request` backend yet; #606 remains open for the
-remaining Bitbucket/Jira workflow coverage. Later PRs can extend the
-same adapter with write operations, Bitbucket Issues, linked Jira
-handoff, branch permissions, and Pipelines status reads.
+This initial bridge implements a `partial-read-only` profile for
+repository metadata context and pull-request discovery/fetching under
+`contract:change-request`. Partial adapters may implement named
+contract verbs, but they do not satisfy the complete contract and must
+not be advertised as complete/selectable backends.
+
+Repository metadata reads are currently bridge context for Bitbucket
+pull-request workflows, not a complete `contract:source-control`
+backend. `contract:tracker` is also intentionally absent until
+Bitbucket issue operations or linked Jira handoff coverage exist.
+#606 remains open for the remaining Bitbucket/Jira workflow coverage.
+Later PRs can extend the same adapter with write operations,
+Bitbucket Issues, linked Jira handoff, branch permissions, and
+Pipelines status reads.
## Prerequisites
@@ -57,6 +68,20 @@ surface:
- `BITBUCKET_KIND=cloud`
- `BITBUCKET_KIND=datacenter`
+## Operation coverage
+
+| Contract area | Operation | Coverage | Notes |
+|---|---|---|---|
+| Repository metadata | `repo get` | Supported read-only context | Reads repository metadata from Bitbucket Cloud or Data Center for Bitbucket PR workflows. This does not make the bridge a complete `contract:source-control` backend. |
+| Change requests | `list_open` / `pr list-open` | Supported read-only | Lists open pull requests with pagination. |
+| Change requests | `get` / `pr get <id>` | Partial read-only | Fetches PR metadata only. Discussion, commits, diffs, checks, review state, and mergeability are not complete yet. |
+| Change requests | `get_discussion` | Not implemented | Follow-up work for #606. |
+| Change requests | `post_review` | Not implemented | Follow-up work for #606. |
+| Change requests | `land` | Not implemented | Follow-up work for #606. |
+| Change requests | `reject` | Not implemented | Follow-up work for #606. |
+| Tracker | issue operations | Not implemented | `contract:tracker` remains absent until Bitbucket issue operations or linked Jira handoff coverage exist. |
+| CI | Pipelines status | Not implemented | Follow-up work for #606. |
+
## Invocation
```bash
@@ -79,6 +104,10 @@ The bridge is configured through environment variables. The calling
skill resolves adopter project configuration and exports these values;
the bridge does not read `<project-config>/` files directly.
+Persistent Bitbucket credentials should live outside the project tree,
+for example under `~/.config/apache-magpie/bitbucket/`, and should be
+injected by the caller as `BITBUCKET_TOKEN` / `BITBUCKET_CLOUD_USER`.
+
| Variable | Required for | Description |
|---|---|---|
| `BITBUCKET_KIND` | all commands | `cloud` or `datacenter`. Defaults to `cloud`. |