chore: update our release process

Author: gustavovalverde

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.changeset/ten-terms-rescue.md

@@ -0,0 +1,5 @@
+---
+"h2m-parser": minor
+---
+
+Fast HTML to Markdown converter with Mozilla Readability extraction, streaming renderer, and LLM-ready output. 3.75x faster than alternatives

.github/workflows/publish-tag.yml

@@ -17,6 +17,9 @@ jobs:
   release:
     name: Release
     runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://www.npmjs.com/package/@lgtm/htmltomd
     steps:
       - name: Checkout
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 #v5.0.0
@@ -35,6 +38,7 @@ jobs:
           node-version: 20
           cache: 'pnpm'
           registry-url: 'https://registry.npmjs.org'
+          always-auth: true
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -57,7 +61,6 @@ jobs:
           createGithubReleases: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN || '' }}  # TODO: remove when OIDC is configured
 
       - name: Publish notification
         if: steps.changesets.outputs.published == 'true'

.github/workflows/release.yml

@@ -2,9 +2,7 @@ node_modules
 .DS_Store
 dist
 coverage
-.results
 .bench
-bench/.results
 bench/output
 fixtures/
 .vscode
@@ -13,9 +11,6 @@ fixtures/
 .env*
 .nyc_output
 
-# Changeset state
-.changeset
-
 # TypeDoc generated documentation
 docs/api
 docs/api-markdown

.gitignore

@@ -21,6 +21,7 @@ Thanks for your interest in improving h2m-parser! Keeping cognitive load low is
 
 - Husky runs `lint-staged` to format/lint staged files. Make sure your commits are clean.
 - Use [Changesets](https://github.com/changesets/changesets) for release notes. After feature work, run `pnpm changeset` to document changes and version bumps.
+- When the release PR opens, review the changelog and, after merging, approve the pending run in the `release` environment to publish.
 - CI runs `pnpm lint`, `pnpm typecheck`, `pnpm test`, and `pnpm build`. Keep the `verify` script green locally before pushing.
 
 ## Reporting issues

CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Release Process
+
+This guide explains how we publish `@lgtm/htmltomd` with Changesets, GitHub Actions, and npm trusted publishing.
+
+## What we use
+
+- **Changesets** to stage version bumps and changelog entries.
+- A single workflow, `.github/workflows/release.yml`, that both opens the release PR and publishes packages.
+- An npm trusted publisher binding that issues ephemeral credentials through GitHub's OIDC provider.
+- A GitHub environment named `release` that gates real publishes (require your approval before jobs run).
+
+## One-time setup (already completed)
+
+1. **Seed npm** – publish the very first version manually (`npm publish --tag alpha --access public`) so the package name exists.
+2. **Configure trusted publishing** – on npm go to *Access → Add trusted publisher* and point it at `gustavovalverde/htmltomd`, workflow `.github/workflows/release.yml`, environment `release`.
+3. **Create the GitHub environment** – in the repo settings add an environment called `release`, add yourself as a required reviewer, and optionally set the URL to `https://www.npmjs.com/package/@lgtm/htmltomd`.
+
+With that in place the workflow no longer needs an `NPM_TOKEN`; it exchanges an id-token for publish credentials automatically.
+
+## Normal release flow
+
+1. **Author changesets** – whenever a PR needs a release entry run `pnpm changeset` and commit the generated file under `.changeset/`.
+2. **Merge feature PRs** – once on `main`, the release workflow opens/updates a `chore(release): version packages` PR with the aggregated changelog.
+3. **Review the release PR** – check the generated CHANGELOG and version bumps. When happy, merge it.
+4. **Approve the publish run** – the merge triggers the `release` job; approve the pending run in the *Actions* tab (required reviewer on the `release` environment). The job builds, tests, publishes via Changesets, and creates the GitHub release notes.
+5. **Verify** – confirm the new version on npm (`npm view @lgtm/htmltomd version`) and skim the release notes.
+
+## Manual triggers
+
+Need to kick a release outside of an automatic merge? Use **Actions → Release → Run workflow**, choose the branch, and approve the run when prompted. The workflow handles the rest.
+
+## Troubleshooting
+
+- *Publish fails with auth errors*: confirm the npm trusted publisher entry still points at `.github/workflows/release.yml` and the `release` environment exists. Re-run the job after fixing.
+- *No release PR appears*: make sure there is at least one unpublished changeset file on `main`; otherwise the workflow exits early. You can run it manually via `workflow_dispatch`.
+- *Need to bypass automation*: as a last resort you can run `pnpm verify && pnpm build && npm publish --access public`, but follow up by re-running `pnpm changeset version` so history stays in sync.
+
+## Retired workflows
+
+We removed `.github/workflows/publish-tag.yml`; tag pushes no longer publish separately. Keep releases flowing through the single Changesets-driven workflow to avoid duplicate logic.