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.
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/.editorconfig +4 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/.github/PULL_REQUEST_TEMPLATE.md +1 -1
- uv_upsync-2.4.3/.github/workflows/ci.yaml +41 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/.github/workflows/release.yaml +42 -20
- uv_upsync-2.4.3/.python-version +1 -0
- uv_upsync-2.4.3/AGENTS.md +70 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/CHANGELOG.md +99 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/CODE_OF_CONDUCT.md +13 -0
- uv_upsync-2.4.3/CONTRIBUTING.md +169 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/PKG-INFO +33 -31
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/README.md +25 -25
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/SECURITY.md +3 -3
- uv_upsync-2.4.1/action.yml → uv_upsync-2.4.3/action.yaml +1 -1
- uv_upsync-2.4.3/assets/logo.svg +1 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/cliff.toml +2 -0
- uv_upsync-2.4.3/justfile +37 -0
- uv_upsync-2.4.3/pyproject.toml +114 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/__init__.py +1 -1
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/__main__.py +5 -6
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/commands.py +2 -2
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/config.py +1 -2
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/logging.py +6 -2
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/parsers.py +5 -9
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/pypi.py +3 -3
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/report.py +1 -2
- uv_upsync-2.4.3/tests/__init__.py +3 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/conftest.py +1 -1
- uv_upsync-2.4.3/uv.lock +806 -0
- uv_upsync-2.4.1/.github/labels.yaml +0 -59
- uv_upsync-2.4.1/.github/workflows/ci.yaml +0 -41
- uv_upsync-2.4.1/.github/workflows/labels.yaml +0 -34
- uv_upsync-2.4.1/.python-version +0 -1
- uv_upsync-2.4.1/CLAUDE.md +0 -60
- uv_upsync-2.4.1/CONTRIBUTING.md +0 -128
- uv_upsync-2.4.1/assets/logo.svg +0 -2
- uv_upsync-2.4.1/justfile +0 -26
- uv_upsync-2.4.1/pyproject.toml +0 -96
- uv_upsync-2.4.1/tests/__init__.py +0 -3
- uv_upsync-2.4.1/uv.lock +0 -521
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/.gitignore +0 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/.pre-commit-hooks.yaml +0 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/LICENSE +0 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/exceptions.py +0 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/src/uv_upsync/uv.py +0 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_commands.py +0 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_config.py +0 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_exceptions.py +0 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_logging.py +0 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_parsers.py +0 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_pypi.py +0 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_report.py +0 -0
- {uv_upsync-2.4.1 → uv_upsync-2.4.3}/tests/test_uv.py +0 -0
|
@@ -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-
|
|
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@
|
|
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@
|
|
37
|
+
uses: astral-sh/setup-uv@v10.1.0
|
|
34
38
|
with:
|
|
35
|
-
python-version: "3.
|
|
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 "$
|
|
41
|
-
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-
|
|
90
|
+
runs-on: ubuntu-24.04-arm
|
|
71
91
|
steps:
|
|
72
92
|
- name: Checkout repository
|
|
73
|
-
uses: actions/checkout@
|
|
93
|
+
uses: actions/checkout@v7
|
|
74
94
|
with:
|
|
75
95
|
ref: ${{ needs.tag.outputs.tag }}
|
|
76
96
|
fetch-depth: 0
|
|
77
97
|
|
|
78
|
-
- name:
|
|
79
|
-
uses:
|
|
80
|
-
id: changelog
|
|
98
|
+
- name: Download release notes
|
|
99
|
+
uses: actions/download-artifact@v8
|
|
81
100
|
with:
|
|
82
|
-
|
|
101
|
+
name: notes
|
|
83
102
|
|
|
84
103
|
- name: Create GitHub Release
|
|
85
|
-
uses: softprops/action-gh-release@
|
|
104
|
+
uses: softprops/action-gh-release@v3
|
|
86
105
|
with:
|
|
87
106
|
tag_name: ${{ needs.tag.outputs.tag }}
|
|
88
|
-
|
|
107
|
+
body_path: notes.md
|
|
89
108
|
|
|
90
|
-
publish:
|
|
109
|
+
publish-pypi:
|
|
91
110
|
needs: [tag, release]
|
|
92
|
-
runs-on: ubuntu-
|
|
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@
|
|
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@
|
|
122
|
+
uses: astral-sh/setup-uv@v10.1.0
|
|
101
123
|
with:
|
|
102
|
-
python-version: "3.
|
|
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 --
|
|
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.
|