Skip to content

docs: Archive 3-dev backport guidance after #791 #793

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
sergehuber merged 1 commit into from
Jun 30, 2026
Merged

docs: Archive 3-dev backport guidance after #791 #793

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
38 changes: 14 additions & 24 deletions .cursor/rules/unomi-3-dev-backport.mdc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,55 +1,45 @@
---
description: UNOMI-875 overlay — backporting unomi-3-dev → master (extends branch-backport.mdc)
description: UNOMI-875 overlay — unomi-3-dev backport lessons (extends branch-backport.mdc)
alwaysApply: true
---

# unomi-3-dev → master (UNOMI-875 Phase 2)
# unomi-3-dev → master (UNOMI-875)

**Status:** Backport phase **complete** (Phase 2 + [#791](https://github.com/apache/unomi/pull/791)). **Active tracker:** `.local-notes/unomi-3.1-remaining-work-plan.md`.

**Historical plans:** `.local-notes/archive/unomi-3-dev-backport-plan-phase2.md` (§1 exclusion register, §2 playbook).

**Generic workflow first:** `.cursor/rules/branch-backport.mdc` (history audit, diff audit, ADD/MODIFY/MERGE).

For this epic, set:
For any future cherry-pick from `unomi-3-dev`, set:

```bash
SOURCE=unomi-3-dev
TARGET=master
```

Local tracker (git-ignored): `.local-notes/unomi-3-dev-backport-plan-phase2.md` — §2e playbook, §1 exclusion register.

## Unomi-specific never

- **Never** replace `master` review refactors with 3-dev monoliths (REST mappers, tracing lifecycle, test harness, shell CRUD fixes).
- **Never** port items in plan §1 exclusion register: REST exception mappers (implement on master patterns), migration scripts (UNOMI-943), security WIP, wholesale 3-dev test harness.
- **Never** port items in archived plan §1 exclusion register: REST exception mappers (implement on master patterns), migration scripts (UNOMI-943), security WIP, wholesale 3-dev test harness.
- **Never** wholesale-checkout `.github/workflows` (master ahead: #780, #957), `AGENTS.md` (#769), migration groovy, `.asf.yaml` rulesets.
- **Never** blind-checkout `extensions/router/**` — master ahead (#756, #779, #780).

## Unomi-specific always

- Check merged Phase 2 PRs (#771–#783, #755, #763, etc.) before assuming master lacks a 3-dev feature.
- Check merged master PRs (#755–#791, etc.) before assuming master lacks a 3-dev feature.
- **MERGE surgically:** `build.sh`, root `pom.xml`, CI — keep master non-interactive CI, Javadoc, IT memory sampler (#780, #957).
- **Docker compose:** additive only (`container_name`, debug ports); **keep** master OpenSearch/ES image pins (3-dev had 3.4.0 regressions vs master 3.0.0).

## Shell CRUD (PR J) — learned 2026-06-10

Shell CSV/table polish from 3-dev is **mostly already on master** (#755, #763). Remaining 3-dev shell diffs often **revert** review fixes (`UndeployDefinition`, `ConsentCrudCommand`, `ApiKeyCrudCommand`, `RuleCrudCommand`, docker pins). Port only:

- New classes (`DistributionCompleter`)
- Additive CLI flags (`Setup --show`, `@Completion`) on top of master defaults
- **Docker compose:** additive only; align image pins with Track E in the remaining-work plan.

**PR 1 incident:** `git log origin/unomi-3-dev..origin/master -- tools/shell-dev-commands/` would have flagged #755/#763 before blind checkout reverted ~20 fixes.
## Shell CRUD — learned 2026-06-10

## Per–mega-PR risk (plan §2e)
Shell polish from 3-dev is **mostly already on master** (#755, #763). Before any shell port:

| PR | Extra risk |
|---|---|
| **2** (V+U) | Wrong feature name breaks Karaf boot — diff `feature.xml` vs master names |
| **3** (L–P) | Security + persistence — never replace mappers/tracing |
| **4** (F3–F4) | Extend master `AbstractRestExceptionMapper`; do not copy 3-dev monoliths |
| **5** (K) | Router only — never bundle; never blind-checkout `extensions/router/**` |
`git log origin/unomi-3-dev..origin/master -- tools/shell-dev-commands/`

## Validation before PR (Unomi)

Run generic checklist from `branch-backport.mdc`, plus:

- `./build.sh --help`
- `mvn -pl <affected-modules> -am compile -DskipTests`
- PR description: “master-first backport; branch-backport + §2e history/diff audit run”
10 changes: 5 additions & 5 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,15 +51,15 @@ Cursor rule: `.cursor/rules/branch-backport.mdc`

## Backporting `unomi-3-dev` → `master` (UNOMI-875)

Active Phase 2 epic. **Apply generic rules above first**, then
`.cursor/rules/unomi-3-dev-backport.mdc` for Unomi-specific exclusions and
mega-PR risks.
**Backport phase complete** (Phase 2 mega-PRs + [#791](https://github.com/apache/unomi/pull/791) final hygiene). **Apply generic rules above** for any future cherry-picks; see
`.cursor/rules/unomi-3-dev-backport.mdc` for standing exclusions.

| | |
|---|---|
| Source | `unomi-3-dev` |
| Source | `unomi-3-dev` (archive/reference only) |
| Target | `master` |
| Local plan | `.local-notes/unomi-3-dev-backport-plan-phase2.md` (git-ignored) |
| **Active local plan** | `.local-notes/unomi-3.1-remaining-work-plan.md` |
| Archived backport plans | `.local-notes/archive/` (Phase 1, Phase 2, #757 stack tracker) |

Unomi-specific reminders:

Expand Down
Loading