Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
65 lines (44 loc) · 4 KB

CONTRIBUTING.md

File metadata and controls

65 lines (44 loc) · 4 KB
Raw

Contributing

Thanks for your interest in improving this skill. This is a living document — Web Forms migrations expose patterns in waves, and the best way the skill gets better is by encoding the patterns people actually hit.

What kind of contributions are most useful

In rough order of impact:

  1. Mappings for third-party controls. If you've migrated a Telerik RadGrid, a DevExpress ASPxGridView, an Infragistics WebDataGrid, an AjaxControlToolkit TabContainer, etc., a PR that adds a section to references/control-mapping.md with the behavior translation is gold. Include the relevant attributes/events you saw in the wild — not just the docs version.
  2. Parser improvements in scripts/analyze_aspx.py. The current parser is a tolerant regex. If you find a .aspx shape it mis-classifies (nested templates, conditional <%# %>, server tags inside attribute values), a fix with a small test case is welcome.
  3. Auth recipes. references/auth-and-session.md covers cookie auth and JWT. If your project used a custom IHttpModule, federated SSO, or something unusual, a section describing the bridge to .NET 8 helps the next person.
  4. Examples. assets/examples/ has one worked migration. More examples (an editable form, a wizard with multiple steps, a master/detail page, a file upload page) make the skill more concrete.

What's out of scope

  • Database migrations. The skill explicitly avoids changing the data layer — it wraps it. PRs that introduce schema rewrites or ORM swaps belong in a different project.
  • Full code-generation pipelines that bypass Claude. The point of the skill is to give Claude better judgment, not to replace it with templating.
  • Style preferences for the Angular code that contradict modern Angular idioms (NgModule-based components when standalone works, RxJS-everywhere when signals fit, etc.). The skill targets Angular 17+ idioms intentionally.

How to test changes locally

If you're changing the scripts:

python3 scripts/inventory.py assets/examples
python3 scripts/analyze_aspx.py assets/examples/before-CustomerList.aspx

If you're changing references, install the skill in a Claude client and run a migration prompt against a sample .aspx. Confirm the relevant reference is being read (Claude should mention reading it) and that the output reflects the new content.

Style

  • Markdown: wrap at ~100 chars where it reads naturally, but don't break sentences for the sake of it. Use tables when the content is genuinely tabular.
  • Code in references: keep examples small and focused. A 200-line example that demonstrates one principle is worse than a 30-line one.
  • Tone: explain why, not just what. The skill is read by Claude, and Claude follows reasoning better than rules. Heavy-handed MUSTs and SHALLs make the skill brittle.
  • Imperative voice in instructions ("Open the reference file" rather than "You should open the reference file").

Commit messages

Conventional Commits style, kept short:

feat(controls): add mapping for Telerik RadGrid
fix(parser): handle TemplateField with nested LinkButton
docs(auth): clarify cookie domain setup for strangler-fig deploys

PR checklist

  • One topic per PR.
  • If you added a reference section, update the table in SKILL.md so Claude knows when to read it.
  • If you added a script feature, update SKILL.md and the README if the user-facing usage changed.
  • If you added an example, link to it from the relevant reference file so it's discoverable.
  • Run the scripts against the examples to confirm nothing broke.

Releasing a new version

  1. Update CHANGELOG.md with the changes under a new version heading.
  2. Bump the version inside SKILL.md frontmatter (add a version: field if missing).
  3. Re-package: any skill-aware tool can re-build the .skill artifact from the source.
  4. Tag the release: git tag v0.x.0 && git push --tags.

Code of conduct

Be kind, be direct, assume good faith. Migrations are frustrating; we're all just trying to delete legacy code.