8000 docs(inkless:sync): align sync guides with PEP 440 version-consistency fixes by tvainika · Pull Request #780 · aiven/inkless · GitHub
[go: up one dir, main page]
Skip to content

docs(inkless:sync): align sync guides with PEP 440 version-consistency fixes #780

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.

Sign up for GitHub

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

Merged
jeqo merged 3 commits into from
Sep 7, 2026
Merged

docs(inkless:sync): align sync guides with PEP 440 version-consistency fixes #780

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
11d21ae
docs(inkless:sync): align sync guides with PEP 440 version-consistenc…
tvainika Sep 2, 2026
d212772
Apply batched suggestions from code review
tvainika Sep 2, 2026
2897f91
fixup!
tvainika Sep 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions inkless-sync/CONFLICT-RESOLUTION-STRATEGY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ Files that are 100% inkless-specific and don't exist in upstream:
| `build.gradle` | Keep inkless module config (`:storage:inkless`), accept upstream plugin versions |
| `gradle/dependencies.gradle` | Add inkless dependencies (assertj, testcontainers) to upstream |
| `settings.gradle` | Verify `storage:inkless` module is included |
| `tests/kafkatest/__init__.py` | `__version__` must be PEP 440 (https://peps.python.org/pep-0440/) compliant: use `{X.Y.Z}.dev0+inkless` for `-SNAPSHOT`, otherwise `{X.Y.Z}+inkless`; never a bare `.inkless`/`-inkless` suffix |
| `tests/kafkatest/version.py`, `committer-tools/kafka-merge-pr.py`, `streams/quickstart/*.pom` | Must match `gradle.properties` exactly (for example `4.3.0-inkless-SNAPSHOT`); the `:verifyVersionConsistency` Gradle task enforces this |

**Resolution**: Manual review required - merge both sets of changes.

Expand Down
6 changes: 6 additions & 0 deletions inkless-sync/MAIN-SYNC-ACTION-PLAN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,12 @@ For each config file (gradle.properties, build.gradle, etc.):
2. Merge manually: upstream changes + inkless config
3. Test with `./gradlew tasks` to verify Gradle works

Also check the auxiliary version files that `:verifyVersionConsistency` enforces
against `gradle.properties`: `tests/kafkatest/__init__.py` (PEP 440; use `{X.Y.Z}.dev0+inkless` for `-SNAPSHOT`, otherwise `{X.Y.Z}+inkless`; never `.inkless`/`-inkless`),
`tests/kafkatest/version.py`, `committer-tools/kafka-merge-pr.py`, and the
`streams/quickstart/*.pom` files (must match `gradle.properties` exactly). Run
Comment thread
jeqo marked this conversation as resolved.
Resolved
`./gradlew verifyVersionConsistency` to confirm.

#### Step 5: Resolve Core Files (30-60 min)
For each core file with inkless modifications:

Expand Down
7 changes: 7 additions & 0 deletions inkless-sync/MAIN-SYNC-PROMPT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,13 @@ For each config file (gradle.properties, build.gradle, gradle/dependencies.gradl
- Keeps inkless module configuration
- Accepts upstream dependency/plugin versions

Also check auxiliary version files enforced by `:verifyVersionConsistency`:
- `tests/kafkatest/__init__.py`: `__version__` must stay PEP 440 compliant. Use `{X.Y.Z}.dev0+inkless` when `gradle.properties` ends with `-SNAPSHOT`, otherwise use `{X.Y.Z}+inkless`; never a bare `.inkless`/`-inkless` suffix.
- `tests/kafkatest/version.py`, `committer-tools/kafka-merge-pr.py`, and
`streams/quickstart/*.pom`: must match `gradle.properties` exactly.

Run `./gradlew verifyVersionConsistency` to confirm before moving on.

Wait for approval before applying changes.
```

Expand Down
5 changes: 5 additions & 0 deletions inkless-sync/MAIN-SYNC-SESSION-TEMPLATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,10 @@ git diff --name-only --diff-filter=U
| | gradle.properties | | |
| | build.gradle | | |
| | gradle/dependencies.gradle | | |
| | tests/kafkatest/__init__.py | PEP 440: `{X.Y.Z}.dev0+inkless` for `-SNAPSHOT`, otherwise `{X.Y.Z}+inkless` | |
| | tests/kafkatest/version.py | Must match `gradle.properties` exactly | |
| | committer-tools/kafka-merge-pr.py | Must match `gradle.properties` exactly | |
| | streams/quickstart/**/pom.xml | Must match `gradle.properties` exactly | |

### Core Files with Inkless Modifications
| # | File | Inkless Additions Needed | Status |
Expand Down Expand Up @@ -111,6 +115,7 @@ make test
- [ ] `storage/inkless/src/main/java/io/aiven/inkless/InklessWriter.java`
- [ ] `docs/inkless/README.md`
- [ ] Version preserved in `gradle.properties`
- [ ] `./gradlew verifyVersionConsistency` passes

### Comparison with Previous Sync
```bash
Expand Down
19 changes: 12 additions & 7 deletions inkless-sync/RELEASE-SYNC-ACTION-PLAN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,21 +92,25 @@ gh pr create --base inkless-4.0 --title "Sync inkless-4.0 to upstream 4.0.1"

### Version Files

These files need the `-inkless` suffix pattern:
These files need the `inkless` suffix pattern:

#### gradle.properties
```properties
version=4.0.1-inkless
```

#### tests/kafkatest/__init__.py
This value must stay PEP 440 (https://peps.python.org/pep-0440/) compliant:
Use `+inkless` as a local version label instead.
```python
Comment thread
tvainika marked this conversation as resolved.
Resolved
__version__ = '4.0.1.inkless'
__version__ = '4.0.1+inkless'
```

#### tests/kafkatest/version.py
Must match `gradle.properties` exactly (verified by the `:verifyVersionConsistency`
Gradle task); don't add an extra `-SNAPSHOT` suffix on top of `-inkless`.
```python
DEV_VERSION = KafkaVersion("4.0.1-inkless-SNAPSHOT")
DEV_VERSION = KafkaVersion("4.0.1-inkless")
```

#### docs/js/templateData.js
Expand All @@ -124,16 +128,17 @@ var context={
DEFAULT_FIX_VERSION = "4.0.1-inkless"
```

### POM Files (Keep Upstream Version)
### POM files (use the `-inkless` version)

These files use standard Apache Kafka versioning for Maven Central compatibility:
These files must match `gradle.properties` exactly; the `:verifyVersionConsistency`
Gradle task enforces this:

- `streams/quickstart/pom.xml`
- `streams/quickstart/java/pom.xml`
- `streams/quickstart/java/src/main/resources/archetype-resources/pom.xml`

```xml
<version>4.0.1</version> <!-- NOT 4.0.1-inkless -->
<version>4.0.1-inkless</version>
```

### Dependencies (gradle/dependencies.gradle)
Expand Down Expand Up @@ -196,7 +201,7 @@ git push -u origin inkless-4.0-sync-4.0.1

Most common scenario:

1. Resolve version files with `-inkless` pattern
1. Resolve version files with `inkless` pattern
2. Commit merge
3. Verify build

Expand Down
23 changes: 14 additions & 9 deletions inkless-sync/RELEASE-SYNC-GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,18 +142,18 @@ Common conflict areas when syncing release branches:
| File | Reason | Resolution |
|------|--------|------------|
| `gradle.properties` | Version changes | Use `{version}-inkless` pattern |
| `tests/kafkatest/__init__.py` | Version changes | Use `{version}.inkless` pattern |
| `tests/kafkatest/version.py` | DEV_VERSION | Use `{version}-inkless-SNAPSHOT` |
| `tests/kafkatest/__init__.py` | Version changes | Use `{version}+inkless` (PEP 440 local version label) |
| `tests/kafkatest/version.py` | DEV_VERSION | Use `{version}-inkless` (matches `gradle.properties` exactly) |
| `docs/js/templateData.js` | Version strings | Use inkless version pattern |
| `committer-tools/kafka-merge-pr.py` | DEFAULT_FIX_VERSION | Use inkless version |
| `gradle/dependencies.gradle` | Dependency changes | Add new upstream deps, verify inkless deps are used |
| `streams/quickstart/*.pom` | Maven versions | Keep upstream version (no -inkless) |
| `streams/quickstart/**/pom.xml` | Maven versions | Use `{version}-inkless` (matches `gradle.properties` exactly) |
| `*.scala` / `*.java` | Import organization | Accept upstream, remove duplicates |
| `.gitignore` | Inkless-specific entries | Keep both inkless and upstream |

### Conflict Resolution Patterns

#### Version Files (use `-inkless` suffix)
#### Version Files (use `inkless` suffix)

```properties
# gradle.properties
Expand All @@ -162,10 +162,14 @@ version=4.0.1-inkless

```python
# tests/kafkatest/__init__.py
__version__ = '4.0.1.inkless'
# This value must stay PEP 440 (https://peps.python.org/pep-0440/) compliant:
# Use "+inkless" as a local version label.
__version__ = '4.0.1+inkless'
Comment thread
tvainika marked this conversation as resolved.
Resolved

# tests/kafkatest/version.py
DEV_VERSION = KafkaVersion("4.0.1-inkless-SNAPSHOT")
# Must match gradle.properties exactly (verified by the ':verifyVersionConsistency'
# Gradle task); don't add an extra "-SNAPSHOT" suffix on top of "-inkless".
DEV_VERSION = KafkaVersion("4.0.1-inkless")
```

```javascript
Expand All @@ -178,11 +182,12 @@ var context={
};
```

#### POM Files (keep upstream version)
#### POM files (use the `-inkless` version)

The `streams/quickstart` POMs use standard Apache versioning for Maven Central compatibility:
The `streams/quickstart` POMs must match `gradle.properties` exactly; the
`:verifyVersionConsistency` Gradle task enforces this:
```xml
<version>4.0.1</version> <!-- NOT 4.0.1-inkless -->
<version>4.0.1-inkless</version>
```

#### Dependencies (merge and verify)
Expand Down
12 changes: 6 additions & 6 deletions inkless-sync/RELEASE-SYNC-PROMPT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ I need to sync the inkless release branch with an upstream Apache Kafka release.
6. **Resolve conflicts**: When conflicts occur, resolve them following these patterns:
- **Version files**: Use `{upstream_version}-inkless` pattern (e.g., `4.0.1-inkless`)
- **gradle/dependencies.gradle**: Add upstream new deps, verify inkless deps are actually used
- **streams/quickstart POMs**: Keep upstream version (no -inkless suffix)
- **streams/quickstart POMs**: Keep upstream version (no `inkless` suffix)
- **Test files**: Accept upstream changes, keep inkless-specific code
- **.gitignore**: Keep both inkless and upstream entries

Expand Down Expand Up @@ -77,16 +77,16 @@ Please help me execute this release sync process.

### Version Files

Files that need `-inkless` suffix:
Files that need `inkless` suffix:
- `gradle.properties` → `version=4.0.1-inkless`
- `tests/kafkatest/__init__.py` → `__version__ = '4.0.1.inkless'`
- `tests/kafkatest/version.py` → `DEV_VERSION = KafkaVersion("4.0.1-inkless-SNAPSHOT")`
- `tests/kafkatest/__init__.py` → `__version__ = '4.0.1+inkless'` (PEP 440 local version label)
- `tests/kafkatest/version.py` → `DEV_VERSION = KafkaVersion("4.0.1-inkless")` (must match `gradle.properties` exactly; verified by the `:verifyVersionConsistency` Gradle task)
- `docs/js/templateData.js` → `"fullDotVersion": "4.0.1-inkless"`
- `committer-tools/kafka-merge-pr.py` → `DEFAULT_FIX_VERSION = "4.0.1-inkless"`

### POM Files (Keep Upstream Version)
### POM files (use the `-inkless` version)

These files use standard Apache Kafka versioning:
These files must match `gradle.properties` exactly (`:verifyVersionConsistency` enforces this):
- `streams/quickstart/pom.xml`
- `streams/quickstart/java/pom.xml`
- `streams/quickstart/java/src/main/resources/archetype-resources/pom.xml`
Expand Down
8 changes: 4 additions & 4 deletions inkless-sync/RELEASE-SYNC-SESSION-TEMPLATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,8 @@ git merge [TAG]
| # | File | Resolution | Status |
|---|------|------------|--------|
| 1 | gradle.properties | `version=[TAG]-inkless` | |
| 2 | tests/kafkatest/__init__.py | `__version__ = '[TAG].inkless'` | |
| 3 | tests/kafkatest/version.py | `DEV_VERSION = KafkaVersion("[TAG]-inkless-SNAPSHOT")` | |
| 2 | tests/kafkatest/__init__.py | `__version__ = '[TAG]+inkless'` (PEP 440 local version label; a bare `.inkless`/`-inkless` suffix fails `packaging.version.Version` parsing in CI) | |
| 3 | tests/kafkatest/version.py | `DEV_VERSION = KafkaVersion("[TAG]-inkless")` (must match `gradle.properties` exactly; verified by the `:verifyVersionConsistency` Gradle task) | |
| 4 | docs/js/templateData.js | Update version strings | |
| 5 | committer-tools/kafka-merge-pr.py | `DEFAULT_FIX_VERSION = "[TAG]-inkless"` | |

Expand All @@ -57,10 +57,10 @@ git merge [TAG]
|---|------|------------------|--------|
| | gradle/dependencies.gradle | | |

### POM Files (Keep Upstream Version)
### POM Files (use the `-inkless` version)
| # | File | Notes | Status |
|---|------|-------|--------|
| | streams/quickstart/pom.xml | No -inkless suffix | |
| | streams/quickstart/pom.xml | Must match `gradle.properties` exactly (`[TAG]-inkless`); verified by `:verifyVersionConsistency` | |
| | streams/quickstart/java/pom.xml | | |

### Test Files
Expand Down
Loading
0