-
Notifications
You must be signed in to change notification settings - Fork 39
feat(tools/sourcehut, tools/vcs): add SourceHut forge bridge and implement Mercurial backend #670
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.
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
Open
onlyarnav
wants to merge
11
commits into
apache:main
Choose a base branch
from
onlyarnav:sourcehut-forge-bridge
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+1,320
−21
Open
Changes from all commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
a68953e
build: add sourcehut tool and workspace registration
onlyarnav 848597d
docs: add README for sourcehut forge bridge
onlyarnav be04d3e
feat: implement Mercurial backend and SourceHut forge bridge source code
onlyarnav 175853f
test: add unit tests for Mercurial backend and SourceHut forge bridge
onlyarnav f0f7ecd
build: update uv lockfile for sourcehut integration
onlyarnav 7ec8391
docs: update registry, capabilities, and vendor neutrality status
onlyarnav bdb110f
fix: resolve CodeQL unused imports and empty except clauses warnings
onlyarnav 90138c6
Merge branch 'main' into sourcehut-forge-bridge
justinmclean b3a6363
docs: resolve markdown table splits and tighten features list
onlyarnav 986cd1c
feat: drop purge --all for Mercurial reset and require label args in CLI
onlyarnav 10756de
test: verify Mercurial worktree reset and SourceHut empty label valid…
onlyarnav File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| <!-- START doctoc generated TOC please keep comment here to allow auto update --> | ||
| <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> | ||
| **Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* | ||
|
|
||
| - [SourceHut (sr.ht) Forge Bridge](#sourcehut-srht-forge-bridge) | ||
| - [Prerequisites](#prerequisites) | ||
| - [Features](#features) | ||
| - [Invocation](#invocation) | ||
| - [Configuration](#configuration) | ||
|
|
||
| <!-- END doctoc generated TOC please keep comment here to allow auto update --> | ||
|
|
||
| # SourceHut (sr.ht) Forge Bridge | ||
|
|
||
| **Capability:** contract:tracker + contract:source-control + contract:mail-archive | ||
|
|
||
| SourceHut (sr.ht) forge bridge implementation for the Apache Magpie framework. It integrates ticket tracking (`todo.sr.ht`), mailing list patchset review (`lists.sr.ht`), CI builds (`builds.sr.ht`), and repository reads (`git.sr.ht` & `hg.sr.ht`) using SourceHut's GraphQL APIs. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - **Runtime:** Python 3.11+ run via `uv` (stdlib-only, no third-party package dependencies at runtime). | ||
| - **CLIs:** `git` (for Git repo interactions) and `hg` (for Mercurial repo interactions). | ||
| - **Credentials / auth:** `SRHT_TOKEN` environment variable containing a SourceHut Personal Access Token (OAuth2 bearer token) with appropriate scopes (e.g. `TICKETS:RW`, `LISTS:R`, `BUILDS:R`, `REPOS:R`). | ||
| - **Network:** Reaches `todo.sr.ht`, `lists.sr.ht`, `builds.sr.ht`, `git.sr.ht`, and `hg.sr.ht` endpoints over HTTPS (`/query`). | ||
|
|
||
| ## Features | ||
|
|
||
| 1. **VCS Repositories:** Reads repo metadata across `git.sr.ht` and `hg.sr.ht`. | ||
| 2. **Issue Tracker:** Read/write operations (create ticket, comment, resolve status, update labels) on `todo.sr.ht` trackers. | ||
| 3. **Mailing Lists:** Reads patchsets and threads from `lists.sr.ht`, mapping them to the uniform PR/MR review abstraction. | ||
| 4. **CI Builds:** Reads job statuses from `builds.sr.ht`. | ||
| 5. **GraphQL client:** Unified command line tool to execute arbitrary queries/mutations across sr.ht subdomains. | ||
|
|
||
| ## Invocation | ||
|
|
||
| ```bash | ||
| # Get ticket details | ||
| uv run --project tools/sourcehut magpie-sourcehut ticket get ~user/tracker-name 123 | ||
|
|
||
| # Create comment on a ticket | ||
| uv run --project tools/sourcehut magpie-sourcehut ticket comment ~user/tracker-name 123 --body "Nice fix!" | ||
|
|
||
| # Check build status | ||
| uv run --project tools/sourcehut magpie-sourcehut build get 123456 | ||
| ``` | ||
|
|
||
| ## Configuration | ||
|
|
||
| The bridge is configured via environment variables: | ||
|
|
||
| | Variable | Description | | ||
| |---|---| | ||
| | `SRHT_TOKEN` | Required. SourceHut personal OAuth2 token with access to target repositories, trackers, and mailing lists. | | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,80 @@ | ||
| # Licensed to the Apache Software Foundation (ASF) under one | ||
| # or more contributor license agreements. See the NOTICE file | ||
| # distributed with this work for additional information | ||
| # regarding copyright ownership. The ASF licenses this file | ||
| # to you under the Apache License, Version 2.0 (the | ||
| # "License"); you may not use this file except in compliance | ||
| # with the License. You may obtain a copy of the License at | ||
| # | ||
| # http://www.apache.org/licenses/LICENSE-2.0 | ||
| # | ||
| # Unless required by applicable law or agreed to in writing, | ||
| # software distributed under the License is distributed on an | ||
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | ||
| # KIND, either express or implied. See the License for the | ||
| # specific language governing permissions and limitations | ||
| # under the License. | ||
|
|
||
| [build-system] | ||
| requires = ["hatchling"] | ||
| build-backend = "hatchling.build" | ||
|
|
||
| [project] | ||
| name = "magpie-sourcehut" | ||
| version = "0.1.0" | ||
| description = "SourceHut (sr.ht) forge bridge for Apache Magpie — provides tracker, patch review, VCS and CI status reads via GraphQL APIs." | ||
| readme = "README.md" | ||
| requires-python = ">=3.11" | ||
| license = { text = "Apache-2.0" } | ||
| dependencies = [] | ||
|
|
||
| [project.scripts] | ||
| magpie-sourcehut = "magpie_sourcehut:main" | ||
|
|
||
| [tool.hatch.build.targets.wheel] | ||
| packages = ["src/magpie_sourcehut"] | ||
|
|
||
| [tool.ruff] | ||
| line-length = 110 | ||
| target-version = "py311" | ||
| src = ["src", "tests"] | ||
|
|
||
| [tool.ruff.lint] | ||
| select = [ | ||
| "E", | ||
| "W", | ||
| "F", | ||
| "I", | ||
| "B", | ||
| "UP", | ||
| "SIM", | ||
| "C4", | ||
| "RUF", | ||
| ] | ||
| ignore = [ | ||
| "E501", | ||
| ] | ||
|
|
||
| [tool.ruff.lint.per-file-ignores] | ||
| "tests/**" = ["B", "SIM"] | ||
|
|
||
| [tool.mypy] | ||
| python_version = "3.11" | ||
| files = ["src", "tests"] | ||
| warn_unused_ignores = true | ||
| warn_redundant_casts = true | ||
| warn_unreachable = true | ||
| check_untyped_defs = true | ||
| no_implicit_optional = true | ||
| disallow_untyped_defs = true | ||
| disallow_incomplete_defs = true | ||
|
|
||
| [[tool.mypy.overrides]] | ||
| module = "tests.*" | ||
| disallow_untyped_defs = false | ||
| disallow_incomplete_defs = false | ||
|
|
||
| [tool.pytest.ini_options] | ||
| minversion = "8.0" | ||
| addopts = "-ra -q" | ||
| testpaths = ["tests"] |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| # Licensed to the Apache Software Foundation (ASF) under one | ||
| # or more contributor license agreements. See the NOTICE file | ||
| # distributed with this work for additional information | ||
| # regarding copyright ownership. The ASF licenses this file | ||
| # to you under the Apache License, Version 2.0 (the | ||
| # "License"); you may not use this file except in compliance | ||
| # with the License. You may obtain a copy of the License at | ||
| # | ||
| # http://www.apache.org/licenses/LICENSE-2.0 | ||
| # | ||
| # Unless required by applicable law or agreed to in writing, | ||
| # software distributed under the License is distributed on an | ||
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | ||
| # KIND, either express or implied. See the License for the | ||
| # specific language governing permissions and limitations | ||
| # under the License. | ||
|
|
||
| """SourceHut forge bridge implementation for Apache Magpie.""" | ||
|
|
||
| from __future__ import annotations | ||
|
|
||
| import sys | ||
| from collections.abc import Sequence | ||
|
|
||
| __all__ = ["main"] | ||
|
|
||
|
|
||
| def main(argv: Sequence[str] | None = None) -> int: | ||
| """CLI entry point.""" | ||
| from magpie_sourcehut.cli import main as cli_main | ||
|
|
||
| try: | ||
| return cli_main(argv) | ||
| except Exception as exc: | ||
| print(f"magpie-sourcehut error: {exc}", file=sys.stderr) | ||
| return 1 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| # Licensed to the Apache Software Foundation (ASF) under one | ||
| # or more contributor license agreements. See the NOTICE file | ||
| # distributed with this work for additional information | ||
| # regarding copyright ownership. The ASF licenses this file | ||
| # to you under the Apache License, Version 2.0 (the | ||
| # "License"); you may not use this file except in compliance | ||
| # with the License. You may obtain a copy of the License at | ||
| # | ||
| # http://www.apache.org/licenses/LICENSE-2.0 | ||
| # | ||
| # Unless required by applicable law or agreed to in writing, | ||
| # software distributed under the License is distributed on an | ||
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | ||
| # KIND, either express or implied. See the License for the | ||
| # specific language governing permissions and limitations | ||
| # under the License. | ||
|
|
||
| """builds.sr.ht build integration.""" | ||
|
|
||
| from __future__ import annotations | ||
|
|
||
| from typing import Any | ||
|
|
||
| from magpie_sourcehut.client import query_graphql | ||
|
|
||
|
|
||
| def get_job(job_id: int) -> dict[str, Any]: | ||
| """Retrieve details of a specific job on builds.sr.ht.""" | ||
| q = """ | ||
| query GetJob($id: Int!) { | ||
| job(id: $id) { | ||
| id | ||
| status | ||
| created | ||
| updated | ||
| note | ||
| tags | ||
| visibility | ||
| image | ||
| runner | ||
| tasks { | ||
| name | ||
| status | ||
| } | ||
| } | ||
| } | ||
| """ | ||
| res = query_graphql("builds", q, {"id": job_id}) | ||
| return res.get("job") or {} |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Heads-up: after the merge with
mainthis now breaks CI.tools/sourcehutdeclarescontract:tracker + contract:source-control + contract:mail-archive, butmainrecently gainedtools/vendor-neutrality-score(#672), which requires every contract tool's README to declare**Kind:**and**Vendor:**. Without them its loader raisesValueErrorand thevendor-neutrality-scorepytest job fails. Please add, e.g.:(Bonus: that also makes SourceHut count as an additional backend for tracker / source-control / mail-archive in the neutrality score.)