uv-upsync 2.4.1__tar.gz → 2.4.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/.editorconfig +4 -0
  2. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/.github/PULL_REQUEST_TEMPLATE.md +1 -1
  3. uv_upsync-2.4.3/.github/workflows/ci.yaml +41 -0
  4. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/.github/workflows/release.yaml +42 -20
  5. uv_upsync-2.4.3/.python-version +1 -0
  6. uv_upsync-2.4.3/AGENTS.md +70 -0
  7. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/CHANGELOG.md +99 -0
  8. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/CODE_OF_CONDUCT.md +13 -0
  9. uv_upsync-2.4.3/CONTRIBUTING.md +169 -0
  10. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/PKG-INFO +33 -31
  11. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/README.md +25 -25
  12. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/SECURITY.md +3 -3
  13. uv_upsync-2.4.1/action.yml → uv_upsync-2.4.3/action.yaml +1 -1
  14. uv_upsync-2.4.3/assets/logo.svg +1 -0
  15. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/cliff.toml +2 -0
  16. uv_upsync-2.4.3/justfile +37 -0
  17. uv_upsync-2.4.3/pyproject.toml +114 -0
  18. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/__init__.py +1 -1
  19. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/__main__.py +5 -6
  20. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/commands.py +2 -2
  21. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/config.py +1 -2
  22. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/logging.py +6 -2
  23. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/parsers.py +5 -9
  24. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/pypi.py +3 -3
  25. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/report.py +1 -2
  26. uv_upsync-2.4.3/tests/__init__.py +3 -0
  27. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/conftest.py +1 -1
  28. uv_upsync-2.4.3/uv.lock +806 -0
  29. uv_upsync-2.4.1/.github/labels.yaml +0 -59
  30. uv_upsync-2.4.1/.github/workflows/ci.yaml +0 -41
  31. uv_upsync-2.4.1/.github/workflows/labels.yaml +0 -34
  32. uv_upsync-2.4.1/.python-version +0 -1
  33. uv_upsync-2.4.1/CLAUDE.md +0 -60
  34. uv_upsync-2.4.1/CONTRIBUTING.md +0 -128
  35. uv_upsync-2.4.1/assets/logo.svg +0 -2
  36. uv_upsync-2.4.1/justfile +0 -26
  37. uv_upsync-2.4.1/pyproject.toml +0 -96
  38. uv_upsync-2.4.1/tests/__init__.py +0 -3
  39. uv_upsync-2.4.1/uv.lock +0 -521
  40. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/.gitignore +0 -0
  41. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/.pre-commit-hooks.yaml +0 -0
  42. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/LICENSE +0 -0
  43. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/exceptions.py +0 -0
  44. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/uv.py +0 -0
  45. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_commands.py +0 -0
  46. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_config.py +0 -0
  47. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_exceptions.py +0 -0
  48. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_logging.py +0 -0
  49. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_parsers.py +0 -0
  50. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_pypi.py +0 -0
  51. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_report.py +0 -0
  52. {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_uv.py +0 -0
@@ -13,3 +13,7 @@ trim_trailing_whitespace = true
13
13
  [{*.py,*.pyi,*.ipynb}]
14
14
  indent_size = 4
15
15
  tab_width = 4
16
+
17
+ [{*.rs}]
18
+ indent_size = 4
19
+ tab_width = 4
@@ -1,6 +1,6 @@
1
1
  # Pull Request Checklist
2
2
 
3
- <!-- Optional — uncomment if this PR closes an issue -->
3
+ <!-- Optional: uncomment if this PR closes an issue -->
4
4
  <!-- Resolves: #issue-number-here -->
5
5
 
6
6
  ## Summary
@@ -0,0 +1,41 @@
1
+ name: CI
2
+
3
+ on:
4
+ pull_request:
5
+ push:
6
+ branches: ["main"]
7
+ workflow_dispatch:
8
+
9
+ concurrency:
10
+ group: ${{ github.workflow }}-${{ github.ref }}
11
+ cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
12
+
13
+ permissions:
14
+ contents: read
15
+
16
+ jobs:
17
+ ci-package:
18
+ runs-on: ubuntu-24.04-arm
19
+ steps:
20
+ - name: Checkout repository
21
+ uses: actions/checkout@v7
22
+
23
+ - name: Install just
24
+ uses: extractions/setup-just@v4
25
+
26
+ - name: Install uv
27
+ uses: astral-sh/setup-uv@v10.1.0
28
+ with:
29
+ python-version: "3.14"
30
+
31
+ - name: Install dependencies
32
+ run: just install-package
33
+
34
+ - name: Run linters
35
+ run: just lint-package
36
+
37
+ - name: Run audit
38
+ run: just audit-package
39
+
40
+ - name: Run tests
41
+ run: just test-package
@@ -10,14 +10,18 @@ on:
10
10
  permissions:
11
11
  contents: write
12
12
 
13
+ concurrency:
14
+ group: release
15
+ cancel-in-progress: false
16
+
13
17
  jobs:
14
18
  tag:
15
- runs-on: ubuntu-latest
19
+ runs-on: ubuntu-24.04-arm
16
20
  outputs:
17
21
  tag: v${{ steps.version.outputs.version }}
18
22
  steps:
19
23
  - name: Checkout repository
20
- uses: actions/checkout@v6
24
+ uses: actions/checkout@v7
21
25
  with:
22
26
  fetch-depth: 0
23
27
 
@@ -30,20 +34,27 @@ jobs:
30
34
  run: echo "$RUNNER_TEMP/git-cliff/bin" >> "$GITHUB_PATH"
31
35
 
32
36
  - name: Install uv
33
- uses: astral-sh/setup-uv@v6
37
+ uses: astral-sh/setup-uv@v10.1.0
34
38
  with:
35
- python-version: "3.13"
39
+ python-version: "3.14"
36
40
 
37
41
  - name: Resolve version
38
42
  id: version
43
+ env:
44
+ INPUT_VERSION: ${{ github.event.inputs.version }}
39
45
  run: |
40
- if [[ -n "${{ github.event.inputs.version }}" ]]; then
41
- VERSION="${{ github.event.inputs.version }}"
46
+ if [[ -n "$INPUT_VERSION" ]]; then
47
+ VERSION="${INPUT_VERSION#v}"
48
+ if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
49
+ echo "version '${INPUT_VERSION}' is not MAJOR.MINOR.PATCH" >&2
50
+ exit 1
51
+ fi
42
52
  else
43
53
  VERSION=$(git-cliff --bumped-version)
44
54
  VERSION="${VERSION#v}"
45
55
  fi
46
56
  echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
57
+ echo "resolved version: ${VERSION}"
47
58
 
48
59
  - name: Update version
49
60
  run: uv version "${{ steps.version.outputs.version }}"
@@ -65,44 +76,55 @@ jobs:
65
76
  git tag "v${VERSION}"
66
77
  git push origin main --tags
67
78
 
79
+ - name: Generate release notes
80
+ run: git-cliff --latest --strip header --output notes.md
81
+
82
+ - name: Upload release notes
83
+ uses: actions/upload-artifact@v7
84
+ with:
85
+ name: notes
86
+ path: notes.md
87
+
68
88
  release:
69
89
  needs: tag
70
- runs-on: ubuntu-latest
90
+ runs-on: ubuntu-24.04-arm
71
91
  steps:
72
92
  - name: Checkout repository
73
- uses: actions/checkout@v6
93
+ uses: actions/checkout@v7
74
94
  with:
75
95
  ref: ${{ needs.tag.outputs.tag }}
76
96
  fetch-depth: 0
77
97
 
78
- - name: Generate Changelog
79
- uses: orhun/git-cliff-action@v4
80
- id: changelog
98
+ - name: Download release notes
99
+ uses: actions/download-artifact@v8
81
100
  with:
82
- args: --latest --strip header
101
+ name: notes
83
102
 
84
103
  - name: Create GitHub Release
85
- uses: softprops/action-gh-release@v2
104
+ uses: softprops/action-gh-release@v3
86
105
  with:
87
106
  tag_name: ${{ needs.tag.outputs.tag }}
88
- body: ${{ steps.changelog.outputs.content }}
107
+ body_path: notes.md
89
108
 
90
- publish:
109
+ publish-pypi:
91
110
  needs: [tag, release]
92
- runs-on: ubuntu-latest
111
+ runs-on: ubuntu-24.04-arm
112
+ permissions:
113
+ contents: read
114
+ id-token: write
93
115
  steps:
94
116
  - name: Checkout repository
95
- uses: actions/checkout@v6
117
+ uses: actions/checkout@v7
96
118
  with:
97
119
  ref: ${{ needs.tag.outputs.tag }}
98
120
 
99
121
  - name: Install uv
100
- uses: astral-sh/setup-uv@v6
122
+ uses: astral-sh/setup-uv@v10.1.0
101
123
  with:
102
- python-version: "3.13"
124
+ python-version: "3.14"
103
125
 
104
126
  - name: Build
105
127
  run: uv build
106
128
 
107
129
  - name: Publish to PyPI
108
- run: uv publish --token ${{ secrets.PYPI_TOKEN }}
130
+ run: uv publish --trusted-publishing always
@@ -0,0 +1 @@
1
+ 3.14
@@ -0,0 +1,70 @@
1
+ # uv-upsync
2
+
3
+ ## What This Is
4
+
5
+ A single-command CLI that raises the **lower bounds of dependency specifiers in `pyproject.toml`** to the latest published versions, then re-locks with `uv`.
6
+
7
+ The distinction that defines the whole project: `uv lock --upgrade` refreshes the **lockfile** but leaves `httpx>=0.24.0` written as `>=0.24.0` forever. `uv-upsync` rewrites the human-authored bound in `pyproject.toml` itself, and does so surgically - only the version token is replaced, so operators, extras, environment markers, spacing and comments survive verbatim.
8
+
9
+ Published to PyPI as `uv-upsync`. `README.md` owns the option table, the `[tool.uv-upsync]` keys and the usage examples.
10
+
11
+ ## Distribution Surfaces
12
+
13
+ Any change to the CLI flags has to land in four places, not one:
14
+
15
+ 1. `src/uv_upsync/__main__.py` - the click options
16
+ 2. `README.md` - the options table and the `[tool.uv-upsync]` example block
17
+ 3. `action.yaml` - the composite GitHub Action (passes `inputs.args` through to `uvx uv-upsync`, captures stdout into a `summary` output for PR bodies)
18
+ 4. `.pre-commit-hooks.yaml` - the `uv-upsync` and `uv-upsync-check` hooks, both `pass_filenames: false` and gated on `^pyproject\.toml$`
19
+
20
+ A new config key also needs a branch in `config.load_config` plus its validator, and the corresponding `flag = flag or settings.flag` line in `cli`.
21
+
22
+ ## Invariants Worth Knowing Before Editing
23
+
24
+ - **Only lower bounds are raised.** `UPGRADABLE_OPERATORS = {">=", ">", "~="}`; `==`/`===` are never touched, and a specifier with more or fewer than exactly one lower-bound clause is skipped entirely. This conservatism mirrors uv's `--upgrade` and is deliberate
25
+ - **Compound specifiers keep their cap.** `upgradable_specifier` splits off a residual `SpecifierSet` (the `<2.0`, the `!=`s) that every candidate version must still satisfy
26
+ - **`_replace_version` is a token swap, not a re-serialization.** It partitions on `;` to protect markers, then does a single `str.replace` from the operator onward. Do not "improve" this into a `str(Requirement)` round-trip - that would normalize the author's formatting, which is exactly what the tool promises not to do
27
+ - **Settings precedence is CLI > `[tool.uv-upsync]` > defaults**, implemented in `cli` as `flag = flag or settings.flag`. This means a falsy CLI value cannot override a truthy config value, which is intended for the flag-shaped options
28
+ - **The lock strategy has three modes.** The full upgrade set is tried first. On failure: `--strict` restores the deep-copied `backup` document and exits 2; the default best-effort mode re-locks incrementally to keep the maximal subset that resolves; `--resolve` additionally binary-searches `eligible_versions` for the highest version of a failing package that does lock. `_apply_with_lock` always rewrites the accepted set at the end, because the last trial may have left a failing candidate on disk
29
+ - **Exit codes:** `0` success, `1` from `--check` when upgrades exist, `2` (`ERROR_EXIT_CODE`) for any error. `main()` catches everything and renders uv-style `error:` lines instead of tracebacks, re-raising the traceback only under `--verbose`
30
+ - **Non-text `--format` implies quiet.** `logger.configure(quiet=quiet or output_format != "text", ...)` keeps stdout parseable
31
+
32
+ ## Architecture
33
+
34
+ Single flow, no plugin system, no async. `__main__.py` is the orchestrator and everything else is a leaf module it calls.
35
+
36
+ ```
37
+ __main__.cli
38
+ -> config.load_config read [tool.uv-upsync] defaults
39
+ -> parsers.iter_dependency_groups locate the live tomlkit arrays
40
+ -> pypi.PyPIClient.fetch_many concurrent PEP 691 lookups
41
+ -> parsers.plan_updates compute the bumps (pure, no mutation)
42
+ -> __main__._apply_with_lock write + `uv lock`, with fallback strategies
43
+ -> report.render / logging.Logger emit the summary
44
+ ```
45
+
46
+ The module boundaries that carry a rule (the rest is `ls src/uv_upsync/`):
47
+
48
+ - `__main__.py` owns the entire click command surface - every flag is declared there - plus the write/lock/rollback orchestration
49
+ - `parsers.py` owns all TOML and specifier logic: group iteration, requirement parsing, eligibility, bump policy, surgical rewrite, conflict extraction from uv's stderr
50
+ - `report.py` is JSON and Markdown renderers only - text output belongs to `logging.Logger`, not to this module
51
+
52
+ ## Commands
53
+
54
+ `just --list` and `CONTRIBUTING.md` carry the recipe table; CI runs the same recipes, so a green `just check` locally means a green CI. One thing the table does not say:
55
+
56
+ - `just update` runs `uv run uv-upsync` against this repo, so it uses the working tree's own version of the tool
57
+
58
+ Run the CLI itself with `uv run uv-upsync ...` (entry point `uv_upsync.__main__:main`).
59
+
60
+ ## Conventions
61
+
62
+ - Module docstrings follow the house phrasing `"""Module that contains ..."""`. Docstrings take sentence punctuation; code comments never end with a period
63
+ - **Tests mirror modules one-to-one** - `tests/test_<module>.py`. Mocking is `pytest-mock`'s `mocker` fixture, never `unittest.mock` directly. `conftest.py` resets `Logger._instance` between tests via an autouse fixture, because the logger is a process-wide singleton
64
+ - Everything else - ruff select and ignores, import style, line length, pytest `addopts` - lives in `pyproject.toml` and is enforced by `just lint`. Add a targeted `# noqa: RULE` at the site (as `__main__.cli` does) rather than widening the global ignores
65
+
66
+ ## Release
67
+
68
+ Fully automated - **do not bump the version in `pyproject.toml` by hand.** The `Release` workflow is `workflow_dispatch` only; git-cliff derives the next version from the commit history (or takes the `version` input), `uv version` writes it, `CHANGELOG.md` is regenerated, the tag is pushed, and PyPI publication goes through trusted publishing.
69
+
70
+ This makes **Conventional Commits load-bearing**: `cliff.toml` sets `filter_unconventional = true`, so a commit that doesn't match a known prefix is dropped from the changelog entirely, and `features_always_bump_minor` / `breaking_always_bump_major` decide the version. Use `<type>(<scope>): <subject>` with scopes like `parsers`, `pypi`, `config`, `cli`. `CONTRIBUTING.md` has the full prefix table, the branch pattern and the CI/CD workflow table.
@@ -2,6 +2,101 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [2.4.3] - 2026-11-20
6
+
7
+ ### Build
8
+
9
+ - **justfile**: Split recipes into package parts
10
+ - **deps**: Upgrade python dependencies
11
+ - **justfile**: Add an audit recipe for known dependency vulnerabilities
12
+ - Standardize the pyproject configuration
13
+ - Standardize just recipes
14
+ - Drop pyupgrade in favor of ruff
15
+ - **deps**: Update dependencies
16
+
17
+ ### CI/CD
18
+
19
+ - Fold audit into ci and standardize the release
20
+
21
+ ### Documentation
22
+
23
+ - Say just update runs the working tree's uv-upsync
24
+ - Describe the standardized recipes
25
+ - Describe format without pyupgrade
26
+ - Move agent instructions from CLAUDE.md to AGENTS.md
27
+
28
+ ### Miscellaneous
29
+
30
+ - Put docstring summaries on the first line
31
+
32
+ ## [2.4.2] - 2026-09-20
33
+
34
+ ### Bug fixes
35
+
36
+ - Import Self from typing-extensions for python 3.10
37
+ - Import Self under TYPE_CHECKING to restore Python 3.10 support
38
+ - **commands**: Widen write_dl rows annotation to Iterable
39
+
40
+ ### Build
41
+
42
+ - Bump python to 3.14
43
+ - Update dependencies
44
+ - Update dependencies
45
+ - Update dependencies
46
+ - **deps**: Update dependency lockfile
47
+ - **deps**: Update dependencies
48
+ - **deps**: Update dependencies
49
+
50
+ ### CI/CD
51
+
52
+ - Pin workflow python to 3.14 and rename action.yml to yaml
53
+ - Pin setup-uv to v10.1.0
54
+ - Drop label sync in favor of terraform
55
+ - Publish to pypi via trusted publishing instead of a token
56
+ - Ignore rules newly stabilized in ruff 0.16
57
+ - Drop ruff format --check from lint; suppress more ty rules
58
+ - Use uv run pytest for project venv; format example file
59
+ - Fix action versions and test recipe failures
60
+ - Drop hashFiles guard; move .no-tests sentinel handling into justfile
61
+ - Flatten to one job per language
62
+ - Bump action versions to latest major
63
+ - Standardize workflow to per-language parallel pipelines on ubuntu-24.04-arm
64
+
65
+ ### Documentation
66
+
67
+ - Use absolute raw url for logo and refresh version notes
68
+ - Rewrite CLAUDE.md from scratch
69
+ - Regenerate CLAUDE.md and add AGENTS.md
70
+ - **release**: Drop trusted publishing header comments
71
+ - Add pull request template
72
+ - Shorten module docstring to fit the line-length limit
73
+ - Regenerate CLAUDE.md
74
+ - Document the module docstring convention
75
+ - Normalize module and package docstrings
76
+ - Normalize punctuation and drop AI-flavored phrasing
77
+ - Refresh CLAUDE.md for current justfile + CI shape
78
+ - **ci**: Document required secrets at top of workflow files
79
+
80
+ ### Miscellaneous
81
+
82
+ - **assets**: Drop svg repo attribution comments
83
+ - Repository housekeeping
84
+ - Symlink AGENTS.md to CLAUDE.md
85
+ - Remove local pull request template
86
+ - **deps**: Update locked dependencies
87
+ - Update dependency lockfile
88
+ - Add editorconfig
89
+ - **justfile**: Use uv lock --upgrade for update, scope pyupgrade to . excluding .venv
90
+ - Standardize justfile recipes and refresh CLAUDE.md
91
+
92
+ ### Refactor
93
+
94
+ - **justfile**: Standardize recipe names and ordering
95
+
96
+ ### Release
97
+
98
+ - V2.4.2
99
+
5
100
  ## [2.4.1] - 2026-05-31
6
101
 
7
102
  ### Build
@@ -24,6 +119,10 @@ All notable changes to this project will be documented in this file.
24
119
 
25
120
  - Tidy logging and parser internals
26
121
 
122
+ ### Release
123
+
124
+ - V2.4.1
125
+
27
126
  ## [2.4.0] - 2026-05-30
28
127
 
29
128
  ### Bug fixes
@@ -1,5 +1,18 @@
1
1
  # Contributor Covenant Code of Conduct
2
2
 
3
+ - [Contributor Covenant Code of Conduct](#contributor-covenant-code-of-conduct)
4
+ - [Our Pledge](#our-pledge)
5
+ - [Our Standards](#our-standards)
6
+ - [Enforcement Responsibilities](#enforcement-responsibilities)
7
+ - [Scope](#scope)
8
+ - [Enforcement](#enforcement)
9
+ - [Enforcement Guidelines](#enforcement-guidelines)
10
+ - [Correction](#correction)
11
+ - [Warning](#warning)
12
+ - [Temporary Ban](#temporary-ban)
13
+ - [Permanent Ban](#permanent-ban)
14
+ - [Attribution](#attribution)
15
+
3
16
  ## Our Pledge
4
17
 
5
18
  We as members, contributors, and leaders pledge to make participation in our community a
@@ -0,0 +1,169 @@
1
+ # Contributing
2
+
3
+ - [Contributing](#contributing)
4
+ - [Reporting Bugs](#reporting-bugs)
5
+ - [How to Submit a Bug Report](#how-to-submit-a-bug-report)
6
+ - [Suggesting Enhancements](#suggesting-enhancements)
7
+ - [How to Submit an Enhancement](#how-to-submit-an-enhancement)
8
+ - [Code Contributions](#code-contributions)
9
+ - [Local Development](#local-development)
10
+ - [CI/CD](#cicd)
11
+ - [Branches](#branches)
12
+ - [Commits](#commits)
13
+ - [Pull Requests](#pull-requests)
14
+
15
+ Thank you for taking the time to contribute.
16
+
17
+ These guidelines are intended to make contributions consistent and easy to review across repositories. They are guidance, not hard instructions, and maintainers may adapt them when needed.
18
+
19
+ ## Reporting Bugs
20
+
21
+ Before creating a bug report, search existing issues to avoid duplicates.
22
+
23
+ When opening a bug report, include enough context for someone else to reproduce the issue and understand the impact.
24
+
25
+ > [!NOTE]
26
+ > If you find a closed issue that looks similar, open a new issue and link the previous one.
27
+
28
+ ### How to Submit a Bug Report
29
+
30
+ Open a bug report and provide the following:
31
+
32
+ - A clear, descriptive title
33
+ - Reproduction steps (minimal and reliable if possible)
34
+ - Current behavior and expected behavior
35
+ - Relevant environment details (for example OS, runtime, browser, framework versions)
36
+ - Logs, stack traces, screenshots, or recordings when useful
37
+
38
+ If the issue is intermittent, describe how often it happens and known triggers.
39
+ If the issue appeared after a change, mention the last known working version or commit if available.
40
+
41
+ ## Suggesting Enhancements
42
+
43
+ Before submitting an enhancement, check whether a similar request already exists.
44
+
45
+ Enhancement requests can include new features, changes to existing behavior, usability improvements, or performance improvements.
46
+
47
+ ### How to Submit an Enhancement
48
+
49
+ Open a feature request and provide the following:
50
+
51
+ - A clear problem statement
52
+ - The proposed solution
53
+ - Alternatives considered or current workarounds
54
+ - Expected impact (who benefits and how)
55
+
56
+ Concrete examples, API sketches, UI mockups, or references are helpful when relevant.
57
+
58
+ ## Code Contributions
59
+
60
+ ### Local Development
61
+
62
+ This repo needs [uv](https://docs.astral.sh/uv), which manages Python 3.14 for you, and `just`.
63
+
64
+ This project uses [`just`](https://github.com/casey/just) as its task runner. Run `just --list` for the full set; these are the ones you need day to day:
65
+
66
+ | Command | What it does |
67
+ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
68
+ | `just install` | Runs `install-package` |
69
+ | `just install-package` | Installs every dependency group and extra into the project virtualenv |
70
+ | `just format` | Runs `format-package` |
71
+ | `just format-package` | Rewrites the sources in place: applies ruff's safe fixes, including its pyupgrade rules for Python 3.10+, and formatting |
72
+ | `just lint` | Runs `lint-package` |
73
+ | `just lint-package` | Lints the project with ruff and type-checks it with ty, without changing any file |
74
+ | `just audit` | Runs `audit-package` |
75
+ | `just audit-package` | Checks the dependencies for known vulnerabilities with uv |
76
+ | `just test` | Runs `test-package` |
77
+ | `just test-package` | Runs the test suite, skipped when the `.no-tests` sentinel is present |
78
+ | `just check` | Runs `lint` then `test` in sequence |
79
+ | `just update` | Runs `update-package` |
80
+ | `just update-package` | Refreshes the lockfile to the latest resolvable versions, then raises the dependency lower bounds in `pyproject.toml` with uv-upsync |
81
+
82
+ 1. Fork the repository and clone your fork locally
83
+ 2. Create a branch using the naming pattern described below
84
+ 3. Make your changes, then run `just check` before opening a pull request
85
+
86
+ > [!IMPORTANT]
87
+ > Behavioral code changes should include or update tests.
88
+
89
+ ### CI/CD
90
+
91
+ Workflows live in `.github/workflows`:
92
+
93
+ | Workflow | Trigger | What it does |
94
+ | --- | --- | --- |
95
+ | CI | Push to `main`, pull requests, `workflow_dispatch` | One job on `ubuntu-24.04-arm`: `ci-package` installs `just` and uv pinned to Python 3.14, installs the project dependencies, then lints the project, audits the locked dependencies, type-checks and tests it through the `*-package` recipes |
96
+ | Release | `workflow_dispatch` (optional `version` input) | Three chained jobs on `ubuntu-24.04-arm`: `tag` takes the version from the `version` input (must be `MAJOR.MINOR.PATCH`) or derives the next one from the commit history with git-cliff, bumps the project version, regenerates `CHANGELOG.md` and pushes the release commit and its tag to `main`, then uploads the release notes as the `notes` artifact; `release` (needs `tag`) publishes the GitHub Release with those notes; `publish-pypi` (needs `tag` and `release`) builds the package and uploads it to PyPI via trusted publishing |
97
+
98
+ CI must be green before a pull request is merged.
99
+
100
+ ### Branches
101
+
102
+ Branch names follow the pattern `<type>/<short-description>` using the same type prefixes as commits.
103
+ The description should be lowercase kebab-case, brief, and specific enough to identify the change at a glance.
104
+
105
+ Examples:
106
+
107
+ ```
108
+ feat/github-token-refresh
109
+ fix/private-repo-archive-auth
110
+ docs/update-sync-flow-diagram
111
+ refactor/mcps-schema-alignment
112
+ ```
113
+
114
+ A branch covering multiple unrelated changes should be split. One concern per branch makes review and bisect much easier.
115
+
116
+ ### Commits
117
+
118
+ Use clear, focused commits with descriptive messages.
119
+
120
+ This project follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
121
+
122
+ **Format**
123
+
124
+ ```
125
+ <type>(<scope>): <subject>
126
+
127
+ [optional body]
128
+ ```
129
+
130
+ - **type** - one of the prefixes from the table below
131
+ - **scope** - the module, command, or area being changed (e.g. `sync`, `mcps`, `github`, `landing`, `config`); omit when the change is truly cross-cutting
132
+ - **subject** - imperative mood, lowercase, no trailing period, 72 characters or fewer
133
+ - **body** - optional; use it to explain _why_, not _what_; wrap at 72 characters
134
+
135
+ **Type prefixes**
136
+
137
+ | Prefix | When to use |
138
+ | ---------- | ------------------------------------------------------------------------------------------------------- |
139
+ | `feat` | A new feature or user-facing capability |
140
+ | `fix` | A bug fix that corrects incorrect behavior |
141
+ | `docs` | Changes to documentation only (README, comments, guides) |
142
+ | `refactor` | Code restructuring that does not change external behavior (renaming, extracting functions, simplifying) |
143
+ | `test` | Adding, updating, or fixing tests without changing production code |
144
+ | `chore` | Maintenance tasks that don't affect source code or tests (dependency bumps, config tweaks, .gitignore) |
145
+ | `ci` | Changes to CI/CD configuration and scripts (GitHub Actions, workflows, pipelines) |
146
+ | `build` | Changes to the build system or external dependencies (Cargo.toml, build scripts, Makefile) |
147
+ | `perf` | A code change that improves performance without altering functionality |
148
+ | `style` | Formatting-only changes (whitespace, semicolons, linting) with no logic changes |
149
+ | `design` | Changes to visual or UI design assets and layout |
150
+ | `revert` | Reverts a previous commit (reference the reverted commit hash in the body) |
151
+
152
+ **Examples**
153
+
154
+ ```
155
+ feat(sync): support skills source sub-directory selection
156
+ fix(github): url-encode git refs in API tarball endpoint
157
+ refactor(mcps): align mcps[] schema with skills[]
158
+ docs(config): document browser URL auto-rewriting for --config
159
+ ```
160
+
161
+ ### Pull Requests
162
+
163
+ - Fill out the pull request template completely
164
+ - Keep the pull request focused and scoped to one change set
165
+ - Ensure tests and checks pass before requesting review
166
+ - Update documentation when behavior or interfaces change
167
+ - Respond to review feedback and keep the branch up to date with the target branch
168
+
169
+ Maintainers may ask for changes, additional tests, or scope adjustments before merging.