Skip to content

Commit 089281a

Browse files
authored
Merge pull request #17 from PerchAnton/edit-session/prepare-1.0
Prepare 1.0 Rust compatibility contract and package checks
2 parents 973a56f + 0ae2f5d commit 089281a

10 files changed

Lines changed: 138 additions & 31 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,7 @@ jobs:
1919
- run: cargo +${{ matrix.rust }} clippy --locked --all-targets -- -D warnings
2020
- run: cargo +${{ matrix.rust }} publish --dry-run --locked --registry crates-io
2121
- run: cargo +${{ matrix.rust }} package --locked
22+
- name: Test the extracted crate contract
23+
run: |
24+
crate_version=$(python3 -c "import tomllib; print(tomllib.load(open('Cargo.toml', 'rb'))['package']['version'])")
25+
cargo +${{ matrix.rust }} test --locked --manifest-path "target/package/edit-session-$crate_version/Cargo.toml"

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Changelog
22

3+
## 1.0.0 — unreleased
4+
5+
- Commit to the documented API, supported platforms and compatible upgrades throughout 1.x.
6+
- Preserve runtime behavior from 0.1.0 and check existing consumers before publication.
7+
- Correct release instructions to require a new matching tag; retain older artifacts.
8+
39
## 0.1.0
410

511
- First non-prerelease, with an explicit 0.1.x patch compatibility and best-effort

‎Cargo.lock‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[package]
22
name = "edit-session"
3-
version = "0.1.0"
3+
version = "1.0.0"
44
edition = "2024"
55
rust-version = "1.88"
66
description = "Toolkit-independent preview, validation and commit lifecycle"

‎PACKAGE.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# edit-session
22

3-
Version **0.1.0** preserves the runnable local-helper comparison and the dependency source guide. Read the [compatibility boundary](https://github.com/PerchAnton/edit-session/blob/main/docs/COMPATIBILITY.md) before upgrading.
3+
This page documents **1.0.0**. Check the [release status](https://github.com/PerchAnton/edit-session/releases/tag/v1.0.0) for registry availability.
4+
5+
Version **1.0.0** preserves the runnable local-helper comparison and the dependency source guide. Read the [compatibility boundary](https://github.com/PerchAnton/edit-session/blob/main/docs/COMPATIBILITY.md) before upgrading.
46

57
A small, toolkit-independent Rust library for preview, validation and commit
68
lifecycles. **`no_std`, zero runtime dependencies, Rust 1.88+.** MIT OR Apache-2.0.
@@ -15,10 +17,10 @@ Add the release to your dependencies:
1517

1618
```toml
1719
[dependencies]
18-
edit-session = "=0.1.0"
20+
edit-session = "=1.0.0"
1921
```
2022

21-
The 0.1.x patch line preserves the documented API. Pin an exact version and keep `Cargo.lock` for
23+
The 1.x line preserves the documented API. Pin an exact version and keep `Cargo.lock` for
2224
applications. Read the
2325
[compatibility policy](https://github.com/PerchAnton/edit-session/blob/main/docs/COMPATIBILITY.md)
2426
before upgrading. For other distribution options and current publication status,

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# edit-session
22

3+
**1.0.0 is being prepared and is not published yet.** Install 0.1.0 until the
4+
[release checklist](https://github.com/PerchAnton/edit-session/blob/main/docs/RELEASE-1.0.md)
5+
is complete. The candidate preserves behavior and defines the 1.x compatibility commitment.
6+
37
Version **0.1.0** preserves the runnable local-helper comparison and the dependency source guide. Read the [compatibility boundary](https://github.com/PerchAnton/edit-session/blob/main/docs/COMPATIBILITY.md) before upgrading.
48

59
Keep an editable draft separate from live data, then check that its document, target
@@ -77,7 +81,7 @@ remains available.
7781
</details>
7882

7983
Trying the library? [Report a bug](https://github.com/PerchAnton/edit-session/issues/new?template=bug_report.yml)
80-
with your revision and a short sequence of calls, or read the [0.1.x compatibility policy](docs/COMPATIBILITY.md).
84+
with your revision and a short sequence of calls, or read the [1.x candidate compatibility policy](docs/COMPATIBILITY.md).
8185

8286
## Retry after a rejected command
8387

‎docs/COMPATIBILITY.md‎

Lines changed: 28 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,23 @@
1-
# Compatibility for 0.1.x
1+
# Compatibility for 1.x
22

33
## Maintenance and versioning
44

5-
This is the first non-prerelease **0.1.0**. Patch releases in 0.1.x preserve the
6-
supported interface below, defaults, error behavior and minimum platform version.
7-
Incompatible changes require a new minor (0.2.0 or later), migration notes and
8-
regression tests; they must not be hidden in a patch. A future 1.0 additionally
9-
requires a separate long-term compatibility review. Internal implementation details
10-
and the exclusions below are not added to the supported API.
5+
This is the compatibility contract for **1.0.0 and the 1.x series**.
6+
The earlier 0.1.0 contract remains available on the v0.1.0 tag.
7+
Version 1.0 introduces a compatibility commitment, without changing runtime behavior.
118

12-
Maintenance is best effort by PerchAnton. Fixes target the latest 0.1.x patch;
13-
older patches and prereleases are not separate support branches. There is no SLA,
14-
fixed maintenance end date, independent security audit or guaranteed response time.
15-
Document deprecations and alternatives before removal. Report reproducible defects
9+
Follow [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html): patches fix
10+
bugs while preserving the documented contract; minor releases add compatible
11+
features or deprecations; incompatible changes require a new major and migration
12+
notes. Deprecations document a replacement and remain available throughout 1.x.
13+
Changes to defaults, error semantics, minimum platforms or existing input limits
14+
are breaking when they invalidate supported consumers. Internal details and the
15+
exclusions below are outside this contract. A bug fix restores documented behavior;
16+
it must include a reproducer and describe any changed result.
17+
18+
Maintenance by PerchAnton is best effort, targeting the latest 1.x release once
19+
published. Older releases remain downloadable, not separate maintenance branches.
20+
There is no SLA, fixed support term or independent security audit. Report defects
1621
with exact versions and synthetic inputs, without secrets or personal documents.
1722
Application owners remain responsible for native regression tests and rollout.
1823

@@ -39,8 +44,8 @@ lock. An `Rc<RefCell<_>>` clone is not an independent snapshot.
3944

4045
## Upgrading and evidence
4146

42-
Pin the exact release (`=0.1.0`). Re-run the host's native
43-
regressions before changing the pin. The upgrade from beta.2 adds no fields to stored documents:
47+
After publication, upgrade the dependency to `=1.0.0` (or `1` for compatible updates). Re-run the host's native
48+
regressions before changing the pin. The upgrade from 0.1.0 adds no fields to stored documents:
4449
sessions are in-memory state, not a serialization format. Error variants are for
4550
branching; Display/Debug prose and memory layout are not a machine protocol.
4651

@@ -50,7 +55,7 @@ examples remain required. Packaging runs those checks from the extracted crate o
5055
the MSRV as well as testing the checkout. These are compatibility checks, not a
5156
claim that an external dependency is better than a correct local helper.
5257

53-
The runtime is unchanged from 0.1.0-beta.2. Existing callers need only change
58+
The runtime is unchanged from 0.1.0. Existing callers need only change
5459
the dependency pin and run their native checks; there is no stored-data migration.
5560
Never replace a published version.
5661

@@ -63,3 +68,12 @@ the feature is useful, which source/owner to accept and how updates are maintain
6368
Keep their source gate intact while that decision is pending; a pin, green CI or
6469
release version does not mean a dependency was reviewed or approved. Running the
6570
separate interaction-check tool in CI needs its own permission/workflow decision.
71+
72+
## Public type evolution
73+
74+
`FinishError` has three exhaustively matchable variants. Adding a variant, adding
75+
fields to `Change<T>` (which supports struct literals), adding required trait
76+
bounds, or losing existing trait implementations requires a major release.
77+
Rust 1.88 and `no_std` remain supported throughout 1.x. New optional methods may
78+
be minor additions only when existing source still compiles. Memory layout and
79+
Debug/Display wording remain outside the contract.

‎docs/RELEASE-1.0.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# 1.0.0 preparation
2+
3+
**Unreleased candidate.** The registry release remains 0.1.0. This change defines
4+
the [1.x commitment](COMPATIBILITY.md), rather than adding another editing abstraction.
5+
`src/lib.rs` is unchanged from 0.1.0; Rust 1.88, no_std and zero dependencies remain.
6+
7+
## Upgrade
8+
9+
After publication, change the dependency pin to `=1.0.0`, retain the lockfile and
10+
run the host's Cancel, Reset, stale target/revision, no-op and rejected-command
11+
regressions. No stored-data migration is needed. A host's source approval policy
12+
still applies to a registry package, organisation-owned source or vendored copy.
13+
See [the source choices and local-helper comparison](source-policy.md).
14+
15+
## Release gates
16+
17+
- [ ] Review the 1.x contract and candidate diff; confirm no runtime changes.
18+
- [ ] Pass MSRV and stable CI, formatting, Clippy, lifecycle/consumer/example tests.
19+
- [ ] Run the same consumer contract against the published 0.1.0 and extracted
20+
1.0.0 crate. Preserve exhaustive error matching and minimal trait bounds.
21+
- [ ] Review the archive inventory, licenses and exact hash, including packaged tests.
22+
- [ ] Review and merge the candidate; require successful CI on main.
23+
- [ ] Obtain release authorization, create a new v1.0.0 tag, then use the existing
24+
crates-io workflow and environment approval. Never reuse v0.1.0.
25+
- [ ] Compare registry archive bytes/hash; run a clean registry consumer before
26+
marking README, release notes or installation instructions as published.
27+
28+
Local results and PR CI are preparation evidence, not proof of publication.
29+
Do not imply that PhotoCraft uses a crates.io dependency: its accepted integration
30+
uses an internal source module. Existing integrations are not upgraded by this release.
31+
32+
## Announcement draft (only after publication)
33+
34+
edit-session 1.0 defines a compatible Rust API for draft validation and one-time
35+
commit decisions. An executable Undo/Reset example shows why restoring a value
36+
does not make an old draft current. The host still owns revisions, commands and
37+
history. Compare the crate with a correct local helper before adding a dependency.

‎docs/RELEASING.md‎

Lines changed: 16 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Releases and compatibility
22

3+
## Next candidate: 1.0.0 (not published)
4+
5+
Follow [the 1.0 checklist](RELEASE-1.0.md). Use a **new** tag matching the reviewed
6+
package version; never reuse v0.1.0. Preparation and CI do not publish a package.
7+
8+
39
## Current non-prerelease 0.1.0
410

511
Published on 7 November 2026 through Trusted Publishing. The exact crate from
@@ -8,14 +14,13 @@ crates.io matches the hosted artifact and passed a clean Rust 1.88 consumer.
814

915
For later releases, require the reviewed
1016
commit to pass the full CI matrix, merge it into main and wait for main CI.
11-
Then create the matching v0.1.0 tag and use the existing Trusted Publishing
17+
Then create a new matching version tag and use the existing Trusted Publishing
1218
workflow with publish=true. Keep environment approval and archive checks intact.
1319
Do not mark the release published until registry hashes and a clean installation
1420
are verified. Publish the GitHub release with prerelease=false and attach the
1521
exact registry artifacts and checksums. Earlier prereleases stay unchanged.
1622

17-
The [0.1.x contract](COMPATIBILITY.md) defines patch compatibility and support;
18-
this release does not claim the separate future 1.0 commitment.
23+
The [published 0.1.x contract](https://github.com/PerchAnton/edit-session/blob/v0.1.0/docs/COMPATIBILITY.md) remains historical. The [candidate 1.x contract](COMPATIBILITY.md) awaits publication.
1924

2025
## Previous beta 0.1.0-beta.2
2126

@@ -43,7 +48,7 @@ A fresh consumer checked commit, no-op, Undo freshness and Reset. Both packaged
4348
and the generated context diagram pass. [Evidence](evidence/release-alpha5.json).
4449
Earlier alpha.4 registry files and alpha.3 GitHub assets remain unchanged.
4550

46-
## Alpha compatibility
51+
## Historical alpha compatibility
4752

4853
- Alpha releases are experimental. Public types, methods, trait bounds and behavior
4954
may change between releases, even within `0.1.0`. Alpha.3 matching alpha.2 does not
@@ -84,10 +89,10 @@ checks the source and example on Rust 1.88 and stable. To validate packaged test
8489
unpack the new `target/package/edit-session-<version>.crate` into a temporary directory
8590
and run `cargo test --locked` and the example from that directory.
8691

87-
A GitHub prerelease can attach the checked `.crate` archive and SHA-256 checksum to
88-
an exact green commit. It is a source archive, not a globally installed executable.
89-
Consumers can continue using a fixed Git revision while the API is experimental.
90-
Do not present an alpha release as the latest stable release.
92+
Attach the checked `.crate` archive and SHA-256 checksum to a release on the
93+
exact green commit. Set `prerelease=false` for 1.0.0; use a prerelease only for
94+
versions labelled alpha, beta or rc. The crate is a source archive, not a globally
95+
installed executable. Preserve the existing releases and their assets.
9196

9297
## Registry publication
9398

@@ -160,15 +165,15 @@ the workflow to re-upload alpha.4 after its manual first publication.
160165

161166
### Verify installation after publication
162167

163-
Use a fresh consumer project and the exact prerelease dependency:
168+
Use a fresh consumer project and the exact newly published dependency:
164169

165170
```toml
166171
[dependencies]
167-
edit-session = "=0.1.0-beta.1"
172+
edit-session = "=<approved-version>"
168173
```
169174

170175
Run `cargo check`, confirm `Cargo.lock` names the crates.io source (not a path/Git
171-
override), and check the [API documentation](https://docs.rs/edit-session/0.1.0-beta.1/).
176+
override), and check the [API documentation](https://docs.rs/edit-session/).
172177
Only then mark the README/changelog as published. Never
173178
overwrite a published version; fixes require a new version.
174179

‎tests/consumer_contract.rs‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,3 +57,38 @@ fn simultaneous_conflicts_have_a_defined_priority() {
5757
Err(FinishError::ContextChanged)
5858
);
5959
}
60+
61+
// Downstream code can exhaustively branch on all errors and destructure changes.
62+
// These are source-compatibility promises, not an invitation to add variants in 1.x.
63+
#[test]
64+
fn exhaustive_error_handling_and_change_literals_remain_supported() {
65+
fn reason(error: FinishError) -> u8 {
66+
match error {
67+
FinishError::InvalidProposal => 1,
68+
FinishError::ContextChanged => 2,
69+
FinishError::ValueChanged => 3,
70+
}
71+
}
72+
assert_eq!(reason(FinishError::InvalidProposal), 1);
73+
assert_eq!(reason(FinishError::ContextChanged), 2);
74+
assert_eq!(reason(FinishError::ValueChanged), 3);
75+
let Change { before, after } = Change {
76+
before: 3,
77+
after: 4,
78+
};
79+
assert_eq!((before, after), (3, 4));
80+
}
81+
82+
#[test]
83+
fn reset_does_not_require_context_traits_or_value_equality() {
84+
#[derive(Clone)]
85+
struct Value(u8);
86+
struct Context;
87+
let mut draft = EditSession::new(Value(3), Context);
88+
assert_eq!(draft.propose::<()>(Ok(Value(4))), Ok(()));
89+
assert_eq!(draft.propose::<()>(Err(())), Err(()));
90+
draft.reset();
91+
assert_eq!(draft.preview().0, 3);
92+
assert!(draft.is_valid());
93+
draft.cancel();
94+
}

0 commit comments

Comments
 (0)