loopwind 0.9.1

package/PUBLISHING.md

@@ -0,0 +1,171 @@
+# Publishing Guide
+
+This guide explains how to publish `dsgn` to npm.
+
+## Prerequisites
+
+1. npm account (create at https://www.npmjs.com/signup)
+2. npm CLI logged in: `npm login`
+3. Package name availability check: `npm search dsgn`
+
+## Pre-publish Checklist
+
+- [ ] Update version in package.json
+- [ ] Run tests (if any): `npm test`
+- [ ] Build the project: `npm run build`
+- [ ] Check dist/ folder exists and contains compiled files
+- [ ] Review .npmignore to ensure only necessary files are published
+- [ ] Update CHANGELOG.md (if exists)
+- [ ] Commit all changes: `git add . && git commit -m "Release v0.1.0"`
+- [ ] Tag release: `git tag v0.1.0`
+
+## Publishing Steps
+
+### 1. Dry Run
+
+First, test what will be published:
+
+```bash
+npm pack --dry-run
+```
+
+This shows you exactly what files will be included in the package.
+
+### 2. Test Locally
+
+You can test the package locally before publishing:
+
+```bash
+npm pack
+npm install -g ./dsgn-0.1.0.tgz
+dsgn --help
+```
+
+### 3. Publish to npm
+
+```bash
+npm publish
+```
+
+Or if the package name is scoped:
+
+```bash
+npm publish --access public
+```
+
+### 4. Verify
+
+Check that it's published:
+
+```bash
+npm view dsgn
+```
+
+Test installation:
+
+```bash
+npx dsgn@latest --help
+```
+
+## Post-publish
+
+- [ ] Push git tags: `git push --tags`
+- [ ] Create GitHub release with changelog
+- [ ] Update documentation
+- [ ] Announce on social media / communities
+
+## Versioning
+
+Follow semantic versioning (semver):
+
+- **Patch** (0.1.1): Bug fixes
+- **Minor** (0.2.0): New features, backwards compatible
+- **Major** (1.0.0): Breaking changes
+
+Update version:
+
+```bash
+npm version patch  # 0.1.0 -> 0.1.1
+npm version minor  # 0.1.0 -> 0.2.0
+npm version major  # 0.1.0 -> 1.0.0
+```
+
+## Package Name Alternatives
+
+If `dsgn` is taken, consider:
+
+- `@yourusername/dsgn` (scoped package)
+- `design-cli`
+- `designkit-cli`
+- `dsgn-cli`
+- `template-dsgn`
+
+Check availability:
+
+```bash
+npm search <package-name>
+```
+
+## Unpublishing
+
+If you need to unpublish (within 72 hours):
+
+```bash
+npm unpublish dsgn@0.1.0
+```
+
+Note: Unpublishing is discouraged. Use `npm deprecate` instead for older versions:
+
+```bash
+npm deprecate dsgn@0.1.0 "Please upgrade to 0.2.0"
+```
+
+## CI/CD Publishing (GitHub Actions)
+
+Create `.github/workflows/publish.yml`:
+
+```yaml
+name: Publish to npm
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+Store your npm token in GitHub repository secrets as `NPM_TOKEN`.
+
+## Beta Releases
+
+Publish beta versions:
+
+```bash
+npm version prerelease --preid=beta  # 0.1.0 -> 0.1.1-beta.0
+npm publish --tag beta
+```
+
+Install beta:
+
+```bash
+npm install dsgn@beta
+```
+
+## Resources
+
+- [npm Publishing Guide](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)
+- [Semantic Versioning](https://semver.org/)
+- [npm CLI Documentation](https://docs.npmjs.com/cli)