feat(ipa): IPA Package config, docs and release workflow

[sphterry]

Proposed changes

• Action to publish new IPA package on version bump
• .npmignore
  • tested with npm pack
• Update CONTRIBUTING.md
  • Move IPA validation contributing.md into the IPA directory Contributing
  • Add mentions of conventional commit requirement
  • Add mention to update changelog on version bump

Note: Follow-up ticket CLOUDP-334400 to separate legacy Spectral ruleset into it's own directory with distinct documentation

Jira ticket: CLOUDP-329998

[wtrocki]

Can you flag the new content? I do not see release procedure present.
In future consider creating tiny PRs that move content to separate them from content creation.

[sphterry]

Lines 71-77. Thank you for flagging, I'll keep that in mind for the future

[wtrocki]

Release Workflow Understanding

Process Overview:

1. Version Bump: Update package.json version in PR
   • Recommendation: Consider using separate PRs for version bumps to maintain clean commit history
2. Version Validation: Automated check verifies version has been incremented
   • Question: What's the decision criteria for version changes? Should we reference changelog or follow semantic versioning guidelines?
3. Package Publication: Automated push to package registry upon merge

Key Assumptions:

1. Quality Gates: Existing CI/CD pipeline on main branch handles build validation and testing before release
2. Manual Updates: Downstream consumers will need to manually update dependencies (no automatic version updates)

Questions for Review:

• Should we establish clear guidelines for when to increment major/minor/patch versions?
• Do we want to enforce changelog updates alongside version bumps?

[lovisaberggren]

There is a file in metrics collector.js that is used to collect exceptions, adoptions, violations when running the IPA validation rules, I think we need to include this in the npm package. Perhaps we can move it into the helper functions instead, and keep metrics to contain things not needed for the spectral run

[sphterry]

No need to move it (or if there is, we can do it in a separate PR). I just change the .npmignore to keep that file in the package. Retested it with npm pack and it works👍

[fmenezes]

In MCP (packaged as npm package) instead of comparing two versions we just check if the current version exists as a git tag, if not proceed with deploy (https://github.com/mongodb-js/mongodb-mcp-server/blob/0083493a5bf5afeca84be6fd2813ca4060347fad/.github/workflows/publish.yaml).

Just FYI, not asking to make any changes at all, I just think it is easier to follow if the check is in the workflow and the execution of the action lives within scripts.

[wtrocki]

Suggested change

	A new version of the IPA package will be released when the version is bumped. Before merging, please run
	A new version of the IPA package will be released when the version in package.json is changed. Before merging, please run

[wtrocki]

Can we check that as part of the release job?

[wtrocki]

Alternatively what I used to do is to run job from tag:

1. User creates tag/release.
2. Job runs to create PR with version change and change log.
3. Once merged package is published and changelog in release notes updated

[sphterry]

The changelog is checked on pull requests by .github/workflows/ipa-changelog.yml after that given pull request is merged, it triggers the release workflow. I didn't know about tags until these PR comments! I wish I'd known sooner

[wtrocki]

I would expect docs covering how package is released.
Version bump is technical implementation

[sphterry]

I've updated it to be a separate checklist, let me know if I missed anything

[wtrocki]

Nit: Some wording/intentions changed. Reordered as we say people to bump package and then generate changelog where we need changelog to figure out how to bump package

Suggested change

	A new version of the IPA package will be released when the version in the package.json is changed. To release a new version:
	- [ ] Determine whether your update is [major/minor/patch] following [semantic versioning](https://semver.org/)
	- [ ] Update the version number in package.json
	- [ ] Run `npm run gen-ipa-changelog` and commit the changes.
	- [ ] Open a PR and ensure the title is conventional and scoped to IPA (ie: `ci(ipa): new version`)
	Release process requires generation of changelog and manual update of version in package.json.
	A new version of the IPA package will be released when the version in the package.json is changed.
	Process:
	- [ ] Run `npm run gen-ipa-changelog` and commit the changes.
	- [ ] Based on changelog determine whether your update is [major/minor/patch] following [semantic versioning](https://semver.org/)
	- [ ] Update the version number in package.json
	- [ ]
	- [ ] Open a PR and ensure the title is conventional and scoped to IPA (ie: `ci(ipa): package release`)

[sphterry]

This is a good point, I made the assumption here that a version bump will have been reviewed internally given commit history. I will add this nit to fix in our documentation changes ticket

[wtrocki]

I made the assumption here that a version bump will have been reviewed internally given commit history.

IMHO Author owns the bump decision. Otherwise you would have all reviewers duplicating the work of author to validate version bumps

[sphterry]

@fmenezes To give context, tags have been rejected for now since they are being used for the FOASCLI release workflow and we want to avoid conflicts. Definitely refinement to consider in the future, but outside the scope of the current epic. Thank you for flagging, I've added a section to the tech design.