basic-package-template

Package Name

Package description

Installation

npm install package-name
# or
pnpm add package-name
# or
yarn add package-name

Usage

import { YourClass } from "package-name";

// Usage example
const instance = new YourClass();

API

YourClass

Description of your main export.

Methods

• method() - Description of method

Development

🔧 Quick Setup

To quickly set up branch protection rules, run the automated script:

# Make sure you have GitHub CLI installed and authenticated
gh auth login

# Run the setup script (choose one method)
./scripts/setup-branch-protection.sh
# or
npm run setup:branch-protection

This script will automatically:

• ✅ Detect your main branch (main/master)
• ✅ Configure branch protection rules
• ✅ Require pull requests before merging
• ✅ Require at least 1 approval
• ✅ Dismiss stale reviews on new commits
• ✅ Disable force pushes and deletions
• ✅ Apply rules to administrators
• ✅ Allow GitHub Actions to create and approve pull requests

🤖 GitHub Actions Permissions

The script automatically configures GitHub Actions to create and approve pull requests. This is essential for:

• Automated releases: Allows semantic-release to create PRs for version bumps and changelog updates
• Dependency updates: Enables Dependabot and other bots to create PRs
• Automated workflows: Permits GitHub Actions to interact with pull requests

To modify this behavior:

# Disable GitHub Actions PR creation/approval
gh api repos/OWNER/REPO/actions/permissions/workflow \
  --method PUT \
  --field can_approve_pull_request_reviews=false

# Re-enable GitHub Actions PR creation/approval
gh api repos/OWNER/REPO/actions/permissions/workflow \
  --method PUT \
  --field can_approve_pull_request_reviews=true

To allow administrators to bypass branch protection:

# Edit the script and change line 54 to:
"enforce_admins": false

Or manually in GitHub: Settings → Branches → Edit rule → Uncheck "Include administrators"

Manual Repository Security Setup (Alternative)

If you prefer manual setup, configure branch protection rules:

Branch Protection Rules

• Go to your GitHub repository
• Navigate to Settings → Branches
• Click "Add rule" for the main/master branch
• Configure the following settings:

Required settings:

• ✅ Require a pull request before merging
• ✅ Require approvals: 1 (or more for team projects)
• ✅ Dismiss stale PR approvals when new commits are pushed
• ✅ Require status checks to pass before merging
• ✅ Require branches to be up to date before merging
• ✅ Require conversation resolution before merging
• ✅ Restrict pushes that create files larger than 100MB

Optional but recommended:

• ✅ Require signed commits
• ✅ Include administrators (applies rules to repo admins too)
• ✅ Allow force pushes: No one (or "Specify who can force push" for admins only)
• ✅ Allow deletions: No one

Status Checks (if you add CI/tests)

If you add testing workflows, also enable:

• ✅ Require status checks to pass before merging
• Add your test workflow names to required checks

This ensures:

• No direct commits to main/master
• All changes go through pull requests
• Code review is mandatory
• Automated releases work properly

Setup for Automated Releases

To enable automated releases, configure the following secrets in your GitHub repository:

1. NPM Token

• Go to npmjs.com and sign in
• Click on your avatar → "Access Tokens"
• Click "Generate New Token" → "Automation"
• Copy the generated token
• In your GitHub repo: Settings → Secrets and variables → Actions
• Click "New repository secret"
• Name: NPM_TOKEN
• Value: paste your npm token

2. GitHub Token

The GITHUB_TOKEN is automatically provided by GitHub Actions, no additional configuration needed.

3. Repository Configuration

Make sure in Settings → Actions → General:

• "Allow GitHub Actions to create and approve pull requests" is checked
• Workflow permissions: "Read and write permissions" is selected

Releases

This project uses semantic-release for automated releases. Use conventional commits:

• feat: - New feature (minor version)
• fix: - Bug fix (patch version)
• feat!: or BREAKING CHANGE: - Breaking change (major version)

Examples:

feat: add new authentication method
fix: resolve memory leak in parser
feat!: remove deprecated API endpoints

Release Process

• Make your commits following conventional commits
• Create a pull request to main/master
• Get code review and approval
• Merge the pull request
• GitHub Actions triggers automatically
• A new release is created if significant changes are detected
• The package is published to npm
• A GitHub release with changelog is generated
• 🤖 Automated repo update: A pull request is automatically created to update package.json version and CHANGELOG.md
• Review and merge the automated PR to keep your repository in sync

License

MIT