|
| 1 | +# CLAUDE.md — ConfuserEx Private Fork |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +Private fork of [mkaring/ConfuserEx](https://github.com/mkaring/ConfuserEx) (.NET obfuscator). |
| 6 | +Public fork: [mcpolo99/ConfuserExx](https://github.com/mcpolo99/ConfuserExx) |
| 7 | + |
| 8 | +### Repository Layout |
| 9 | + |
| 10 | +- **Origin** (`origin`): `mcpolo99/private-ConfuserEx` — private repo with stealth fingerprint removal |
| 11 | +- **Upstream** (`upstream`): `mcpolo99/ConfuserExx` — public fork |
| 12 | +- **Mkaring** (`mkaring`): `mkaring/ConfuserEx` — original upstream (dormant since 2022) |
| 13 | + |
| 14 | +### Private vs Public |
| 15 | + |
| 16 | +The ONLY difference is the fingerprint removal commit on top of public main. |
| 17 | +All other changes go to the public repo first, then sync to private. |
| 18 | + |
| 19 | +**NEVER push private commits to upstream (public).** |
| 20 | + |
| 21 | +### Sync Workflow |
| 22 | + |
| 23 | +```bash |
| 24 | +# Sync public into private |
| 25 | +git fetch upstream |
| 26 | +git checkout main |
| 27 | +git rebase upstream/main |
| 28 | +# → Private commits stay on top |
| 29 | +git push origin main |
| 30 | +``` |
| 31 | + |
| 32 | +--- |
| 33 | + |
| 34 | +## Branch & Commit Conventions |
| 35 | + |
| 36 | +See [CONTRIBUTING.md](CONTRIBUTING.md) for the full convention. Summary: |
| 37 | + |
| 38 | +### Branches |
| 39 | + |
| 40 | +| Scenario | Pattern | Example | |
| 41 | +|----------|---------|---------| |
| 42 | +| Issue exists | `{number}-{slug}` | `54-nuget-packages` | |
| 43 | +| Feature | `feature/{description}` | `feature/add-symbol-server` | |
| 44 | +| Chore | `chore/{description}` | `chore/update-dependencies` | |
| 45 | +| Docs | `docs/{description}` | `docs/add-plugin-guide` | |
| 46 | +| Hotfix | `hotfix/{description}` | `hotfix/crash-on-startup` | |
| 47 | +| Experiment | `experiment/{description}` | `experiment/avalonia-port` | |
| 48 | + |
| 49 | +**Create from issue**: `gh issue develop 42 --checkout` |
| 50 | +**Create without issue**: `git checkout -b feature/description develop` |
| 51 | + |
| 52 | +### Commits |
| 53 | + |
| 54 | +Full words, no parenthesized scopes: |
| 55 | + |
| 56 | +``` |
| 57 | +feature: add target manager with credential storage (#54) |
| 58 | +fix: handle locked file exception (#42) |
| 59 | +chore: update dependencies |
| 60 | +test: add cross-framework integration tests |
| 61 | +``` |
| 62 | + |
| 63 | +### Branch Flow |
| 64 | + |
| 65 | +``` |
| 66 | +main — stable, releases only |
| 67 | + develop — integration branch, all PRs target here |
| 68 | +``` |
| 69 | + |
| 70 | +- PRs target `develop`, NOT `main` |
| 71 | +- When develop is stable → merge commit from `develop` → `main` (triggers release) |
| 72 | +- **Always use merge commit (not squash) for develop→main** to keep history aligned |
| 73 | + |
| 74 | +--- |
| 75 | + |
| 76 | +## Issue & PR Rules (MANDATORY) |
| 77 | + |
| 78 | +These rules apply to ALL work — our own repo (`mcpolo99/ConfuserExx`) and upstream (`mkaring/ConfuserEx`). |
| 79 | + |
| 80 | +### 1. Before starting any work |
| 81 | + |
| 82 | +- Check if the issue/PR is still open and relevant |
| 83 | +- Check if a fix already exists in our codebase (search commits, PRs, branches) |
| 84 | +- Close issues that are already resolved — comment with the commit hash |
| 85 | +- **Only work on OPEN issues** — skip closed, wontfix, duplicate, invalid |
| 86 | + |
| 87 | +### 2. Review all PRs thoroughly |
| 88 | + |
| 89 | +- Read the actual diff, not just the title or description |
| 90 | +- Review for correctness, not just intent |
| 91 | +- Check for regressions, missing edge cases, or poor patterns |
| 92 | +- Verify the fix actually solves the stated problem |
| 93 | +- Check if there's a better approach |
| 94 | +- **Do NOT merge without understanding what the code does** |
| 95 | + |
| 96 | +### 3. When cherry-picking from mkaring/ConfuserEx |
| 97 | + |
| 98 | +- Fetch the PR: `git fetch mkaring pull/<number>/head:pr-<number>` |
| 99 | +- Check if the change conflicts with our existing modifications |
| 100 | +- Test that the cherry-pick applies cleanly |
| 101 | +- **Do NOT blindly cherry-pick — review the code first** |
| 102 | + |
| 103 | +### 4. When creating issues |
| 104 | + |
| 105 | +- For upstream issues: create matching issues on our repo, reference the original |
| 106 | +- Mention the original reporter when posting fixes |
| 107 | +- Tag with appropriate labels (enhancement, bug, upstream) |
| 108 | +- Include clear reproduction steps and expected vs actual behavior |
| 109 | + |
| 110 | +### 5. PR workflow |
| 111 | + |
| 112 | +- Always push fixes to the **same branch** — never create replacement PRs |
| 113 | +- When a PR gets review feedback, push additional commits to the same branch |
| 114 | +- When a tester reports issues, fix on the same branch and ask for re-test |
| 115 | +- Reference the issue number in commits: `fix: handle timeout (#42)` |
| 116 | +- PR description must include `Fixes #<number>` to auto-close the issue |
| 117 | + |
| 118 | +--- |
| 119 | + |
| 120 | +## Core Project Goal: Support ALL .NET Frameworks |
| 121 | + |
| 122 | +ConfuserExx MUST support obfuscating assemblies targeting ANY .NET framework: |
| 123 | +- .NET Framework 2.0, 3.5, 4.x |
| 124 | +- .NET Standard 2.0 |
| 125 | +- .NET Core 3.x |
| 126 | +- .NET 5, 6, 7, 8, 10+ |
| 127 | + |
| 128 | +Never introduce changes that break older framework compatibility. |
| 129 | + |
| 130 | +--- |
| 131 | + |
| 132 | +## Build & Test |
| 133 | + |
| 134 | +```bash |
| 135 | +# Full build (requires VS 2025+ / MSBuild 18) |
| 136 | +msbuild Confuser2.sln -p:Configuration=Release |
| 137 | + |
| 138 | +# .NET projects only (without C++/CLI test) |
| 139 | +dotnet build Confuser2.sln -c Release |
| 140 | + |
| 141 | +# Run tests |
| 142 | +dotnet test Confuser2.sln -c Release |
| 143 | + |
| 144 | +# Clean |
| 145 | +./scripts/clean-build-artifacts.sh |
| 146 | +``` |
| 147 | + |
| 148 | +### Target Frameworks |
| 149 | + |
| 150 | +| Project | TFM | |
| 151 | +|---------|-----| |
| 152 | +| Core, Protections, Renamer, DynCipher | net48 + netstandard2.0 | |
| 153 | +| GUI (ConfuserEx) | net10.0-windows | |
| 154 | +| CLI (Confuser.CLI) | net10.0 | |
| 155 | +| Runtime | net20 (injected into targets) | |
| 156 | + |
| 157 | +--- |
| 158 | + |
| 159 | +## CI/CD |
| 160 | + |
| 161 | +| Workflow | Trigger | Purpose | |
| 162 | +|----------|---------|---------| |
| 163 | +| `lint.yml` | Every push | Format + style + Roslyn analyzers (no build, ~2 min) | |
| 164 | +| `ci.yml` | PRs + main/develop push | Full build + package + release | |
| 165 | +| `test.yml` | PRs only | Full build + test + coverage + PR comment | |
| 166 | +| `codeql` | Weekly (if changes) + manual | Security analysis | |
| 167 | + |
| 168 | +--- |
| 169 | + |
| 170 | +## Working with Remotes |
| 171 | + |
| 172 | +```bash |
| 173 | +# Push to public (ConfuserExx) |
| 174 | +git push upstream <branch> |
| 175 | + |
| 176 | +# Push to private |
| 177 | +git push origin <branch> |
| 178 | + |
| 179 | +# Create PR on public |
| 180 | +gh pr create --repo mcpolo99/ConfuserExx --head <branch> --base develop |
| 181 | + |
| 182 | +# Create PR from issue |
| 183 | +gh issue develop 42 --checkout --repo mcpolo99/ConfuserExx |
| 184 | +``` |
0 commit comments