From c2f98dd660afac5b5fb25f70b950d39b392c9605 Mon Sep 17 00:00:00 2001 From: Raed Bahri Date: Sat, 24 May 2025 01:31:51 +0100 Subject: [PATCH 1/3] fix: new release workflow --- .github/release-drafter.yml | 48 ++++++++++++-- .github/workflows/pr-checks.yml | 110 ++++++++++++++++++++++++++++++++ .github/workflows/release.yml | 45 +++---------- CONTRIBUTING.md | 104 ++++++++++++++++++++++++++---- package.json | 14 ++-- readme.md | 48 ++++++++++++++ 6 files changed, 307 insertions(+), 62 deletions(-) create mode 100644 .github/workflows/pr-checks.yml diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml index dc94fb4..c1b27b1 100644 --- a/.github/release-drafter.yml +++ b/.github/release-drafter.yml @@ -1,7 +1,7 @@ name-template: 'v$RESOLVED_VERSION' tag-template: 'v$RESOLVED_VERSION' -# Include all changes, not just PRs +# Configuration for PR-based workflow include-pre-releases: false commitish: master @@ -10,24 +10,28 @@ categories: labels: - 'feature' - 'enhancement' + collapse-after: 3 - title: '๐Ÿ› Bug Fixes' labels: - 'bug' - 'fix' + collapse-after: 3 - title: '๐Ÿ“š Documentation' labels: - 'documentation' - 'docs' + collapse-after: 3 - title: '๐Ÿงน Maintenance' labels: - 'maintenance' - 'chore' - 'dependencies' + collapse-after: 3 - title: 'โš ๏ธ Breaking Changes' labels: - 'breaking-change' -change-template: '- $TITLE @$AUTHOR' +change-template: '- $TITLE (#$NUMBER) @$AUTHOR' no-changes-template: '- No changes' change-title-escapes: '\<*_&' @@ -68,31 +72,65 @@ exclude-labels: - 'invalid' - 'wontfix' -# Enhanced autolabeler for conventional commits +# Enhanced autolabeler for conventional commits and files autolabeler: - label: 'feature' title: - '/^feat(\(.+\))?\!?:/i' + - '/^Feature:/i' + branch: + - '/^feature\/.+/' + - '/^feat\/.+/' - label: 'bug' title: - '/^fix(\(.+\))?\!?:/i' + - '/^Fix:/i' + - '/^Bug:/i' + branch: + - '/^fix\/.+/' + - '/^bug\/.+/' + - '/^hotfix\/.+/' - label: 'documentation' title: - '/^docs(\(.+\))?\!?:/i' + - '/^Documentation:/i' files: - '*.md' - - 'docs/**' + - 'docs/**/*' + - '.github/**/*' + branch: + - '/^docs\/.+/' - label: 'chore' title: - '/^chore(\(.+\))?\!?:/i' - '/^ci(\(.+\))?\!?:/i' - '/^build(\(.+\))?\!?:/i' - '/^refactor(\(.+\))?\!?:/i' + - '/^Chore:/i' + files: + - 'package.json' + - 'package-lock.json' + - '.github/workflows/**/*' + - '.gitignore' + - 'tsconfig.json' + - 'biome.json' + branch: + - '/^chore\/.+/' + - '/^refactor\/.+/' + - label: 'dependencies' + title: + - '/^(chore|build)(\(.+\))?\!?:\s*(bump|update|upgrade)/i' + files: + - 'package.json' + - 'package-lock.json' - label: 'breaking-change' title: - '/^.*\!:/i' + - '/^BREAKING CHANGE:/i' -# Replacers to clean up commit messages +# Replacers to clean up commit messages in release notes replacers: - search: '/^(feat|fix|docs|chore|ci|build|refactor)(\(.+\))?\!?:\s*/i' replace: '' + - search: '/^(Feature|Fix|Bug|Documentation|Chore):\s*/i' + replace: '' diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml new file mode 100644 index 0000000..fc12dda --- /dev/null +++ b/.github/workflows/pr-checks.yml @@ -0,0 +1,110 @@ +name: Branch Protection & PR Checks + +on: + pull_request: + types: [opened, synchronize, reopened] + +jobs: + # Lint and validate PR title + pr_validation: + name: PR Validation + runs-on: ubuntu-latest + steps: + - name: Validate PR title + uses: amannn/action-semantic-pull-request@v5 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + # Configure which types are allowed (newline-delimited). + types: | + feat + fix + docs + style + refactor + perf + test + build + ci + chore + revert + # Configure which scopes are allowed (newline-delimited). + # These are optional and can be omitted. + scopes: | + cli + commands + docs + ci + deps + # Configure that a scope is required. + requireScope: false + # Configure additional validation for the subject based on a regex. + # This example ensures the subject doesn't start with an uppercase character. + subjectPattern: ^(?![A-Z]).+$ + # If you use GitHub Enterprise, you can set this to the URL of your server + # githubBaseUrl: https://github.myorg.com/api/v3 + # Configure additional validation for the subject based on a regex. + subjectPatternError: | + The subject "{subject}" found in the pull request title "{title}" + didn't match the configured pattern. Please ensure that the subject + doesn't start with an uppercase character. + + # Check for required files and structure + project_structure: + name: Project Structure Check + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Check required files + run: | + echo "Checking for required files..." + + required_files=( + "package.json" + "README.md" + "CHANGELOG.md" + "LICENSE" + "CONTRIBUTING.md" + ".github/workflows/release.yml" + ".github/release-drafter.yml" + ) + + missing_files=() + + for file in "${required_files[@]}"; do + if [[ ! -f "$file" ]]; then + missing_files+=("$file") + fi + done + + if [[ ${#missing_files[@]} -gt 0 ]]; then + echo "โŒ Missing required files:" + printf '%s\n' "${missing_files[@]}" + exit 1 + else + echo "โœ… All required files are present" + fi + + # Add a label based on PR size + pr_size_labeler: + name: PR Size Labeler + runs-on: ubuntu-latest + permissions: + pull-requests: write + steps: + - name: Label PR based on size + uses: codelytv/pr-size-labeler@v1 + with: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + xs_label: 'size/XS' + xs_max_size: '10' + s_label: 'size/S' + s_max_size: '100' + m_label: 'size/M' + m_max_size: '500' + l_label: 'size/L' + l_max_size: '1000' + xl_label: 'size/XL' + fail_if_xl: 'false' diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6c98ff3..2a2dada 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,6 +1,8 @@ name: Release & Publish on: + pull_request: + types: [opened, synchronize, reopened] push: branches: - master @@ -8,7 +10,7 @@ on: types: [published] jobs: - # Build and test the project + # Build and test the project for all PRs and pushes build: name: Build & Test runs-on: ubuntu-latest @@ -36,49 +38,18 @@ jobs: with: name: dist path: dist/ - # Create release draft using release-drafter - create_release_draft: - name: Create Release Draft + + # Update release draft when changes are pushed to master + update_release_draft: + name: Update Release Draft if: github.event_name == 'push' && github.ref == 'refs/heads/master' needs: build runs-on: ubuntu-latest permissions: contents: write - pull-requests: write + pull-requests: read steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - - name: Check if release is needed - id: check_commits - run: | - # Get last tag - LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "") - echo "Last tag: $LAST_TAG" - - # Get commits since last tag - if [ -z "$LAST_TAG" ]; then - COMMITS=$(git log --oneline --pretty=format:"%s") - else - COMMITS=$(git log ${LAST_TAG}..HEAD --oneline --pretty=format:"%s") - fi - - echo "Commits since last tag:" - echo "$COMMITS" - - # Check if there are any commits that warrant a release - SHOULD_RELEASE=false - if echo "$COMMITS" | grep -qE "^(feat|fix|perf|revert|docs|style|refactor|test|build|ci|chore|BREAKING CHANGE)"; then - SHOULD_RELEASE=true - fi - - echo "Should release: $SHOULD_RELEASE" - echo "should_release=$SHOULD_RELEASE" >> $GITHUB_OUTPUT - - name: Run Release Drafter - if: steps.check_commits.outputs.should_release == 'true' uses: release-drafter/release-drafter@v5 with: config-name: release-drafter.yml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 04a4e39..12c86fb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,22 +3,100 @@ First off, thank you for considering contributing to BlogForge! It's people like you that make BlogForge such a great tool. -## Where do I go from here? +## ๐Ÿš€ Quick Start +1. **Fork the repository** and clone it locally +2. **Create a feature branch** from `master`: `git checkout -b feat/your-feature-name` +3. **Make your changes** following our guidelines +4. **Submit a pull request** -If you've noticed a bug or have a question, [search the issue tracker](https://github.com/your-username/blogforge/issues) to see if someone else has already reported the issue. If not, feel free to open a new issue. +## ๐Ÿ“‹ Development Process -If you're looking to contribute code, please follow these steps: +### Branch Naming Convention -1. **Fork the repository** and clone it locally. -2. **Create a new branch** for your contribution: `git checkout -b my-new-feature` -3. **Make your changes** and ensure they adhere to the project's coding style. -4. **Write tests** for your changes. -5. **Run the tests**: `npm test` (You'll need to add a test script to your `package.json`) -6. **Commit your changes**: `git commit -am 'Add some feature'` -7. **Push to the branch**: `git push origin my-new-feature` -8. **Submit a pull request** with a clear description of your changes. +Please use the following branch naming convention: +- `feat/feature-name` - for new features +- `fix/bug-name` - for bug fixes +- `docs/description` - for documentation updates +- `chore/description` - for maintenance tasks +- `refactor/description` - for code refactoring -## Code of Conduct +### Commit Message Convention -This project and everyone participating in it is governed by the [BlogForge Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [your-email@example.com](mailto:your-email@example.com). +We follow [Conventional Commits](https://www.conventionalcommits.org/). Your commit messages should be structured as follows: + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +**Types:** +- `feat`: A new feature +- `fix`: A bug fix +- `docs`: Documentation only changes +- `style`: Changes that do not affect the meaning of the code +- `refactor`: A code change that neither fixes a bug nor adds a feature +- `perf`: A code change that improves performance +- `test`: Adding missing tests or correcting existing tests +- `chore`: Changes to the build process or auxiliary tools + +**Examples:** +``` +feat(cli): add new article template command +fix(images): resolve image optimization bug +docs: update installation instructions +``` + +### Pull Request Process + +1. **Create a descriptive PR title** following conventional commit format +2. **Fill out the PR template** completely +3. **Ensure all CI checks pass** +4. **Request review** from maintainers +5. **Address feedback** promptly +6. **Keep your branch up to date** with master + +### Code Quality Standards + +- **Linting**: Run `npm run lint` before committing +- **Building**: Ensure `npm run build` passes +- **Testing**: Add tests for new features (when test framework is available) +- **Documentation**: Update documentation for API changes + +## ๐Ÿ› Reporting Bugs + +Please use our [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) when reporting bugs. + +## ๐Ÿ’ก Suggesting Features + +Please use our [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) when suggesting new features. + +## ๐Ÿ“ Code of Conduct + +This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. + +## ๐ŸŽฏ What We're Looking For + +- **Bug fixes**: Help us squash those pesky bugs! +- **New features**: Add functionality that benefits the community +- **Documentation**: Improve existing docs or add new ones +- **Performance**: Make BlogForge faster and more efficient +- **Testing**: Add test coverage for existing functionality + +## ๐Ÿšซ What We're Not Looking For + +- **Breaking changes** without proper discussion +- **Large refactors** without prior agreement +- **Features that don't fit** the project scope + +## โšก Quick Tips + +- **Keep PRs small** and focused on a single change +- **Write clear commit messages** following our convention +- **Update documentation** when needed +- **Be patient** - reviews take time, but we appreciate your contribution! + +Thank you for contributing! ๐ŸŽ‰ diff --git a/package.json b/package.json index 9a6bd31..6531ae0 100644 --- a/package.json +++ b/package.json @@ -7,9 +7,7 @@ "bin": { "blogforge": "dist/index.js" }, - "files": [ - "dist" - ], + "files": ["dist"], "scripts": { "build": "tsup src/index.ts --format esm --dts", "dev": "tsx src/index.ts", @@ -21,7 +19,11 @@ "format:fix": "biome format --write ./src", "prepare": "husky", "release": "standard-version", - "commit": "cz" + "commit": "cz", + "workflow:migrate": "bash scripts/migrate-to-pr-workflow.sh", + "workflow:help": "echo 'See docs/DEVELOPMENT_WORKFLOW.md for complete guide'", + "pr:ready": "npm run lint && npm run build && echo 'PR ready! โœ…'", + "sync:upstream": "git fetch upstream && git checkout master && git merge upstream/master && git push origin master" }, "keywords": [ "nuxt", @@ -129,9 +131,7 @@ } }, "lint-staged": { - "*.{js,ts,tsx}": [ - "biome check --write" - ] + "*.{js,ts,tsx}": ["biome check --write"] }, "homepage": "https://github.com/lord007tn/BlogForge", "bugs": { diff --git a/readme.md b/readme.md index 419c990..8f2ef23 100644 --- a/readme.md +++ b/readme.md @@ -143,6 +143,54 @@ Contributions are welcome! Please feel free to submit a Pull Request. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines. +## Development Workflow + +1. **Fork** the repository +2. **Clone** your fork locally +3. **Create a feature branch**: `git checkout -b feat/your-feature-name` +4. **Make your changes** following our [coding standards](CONTRIBUTING.md) +5. **Commit** using [conventional commits](https://www.conventionalcommits.org/): + ```bash + git commit -m "feat(cli): add new article template command" + ``` +6. **Push** to your fork: `git push origin feat/your-feature-name` +7. **Create a Pull Request** with a clear description + +### Quick Commands + +```bash +# Install dependencies +npm install + +# Lint code +npm run lint + +# Build project +npm run build + +# Run in development +npm run dev +``` + +### Branch Protection + +Our `master` branch is protected with the following rules: +- โœ… Pull request reviews required (1 approval) +- โœ… Status checks must pass (Build & Test, PR Validation) +- โœ… Branches must be up to date +- โœ… Conversations must be resolved +- โŒ Force pushes disabled + +### Release Process + +We use [Release Drafter](https://github.com/release-drafter/release-drafter) to automatically generate release notes from Pull Requests. The release process is: + +1. **Merge PRs** to `master` - this updates the release draft +2. **Review** the generated release notes +3. **Publish** the release - this triggers npm publishing + +For more details, see [CONTRIBUTING.md](CONTRIBUTING.md). + ## BlogForge CLI: Future Implementation Roadmap ### AI SDK Integration From 66aee0599bf77abf34d11ae38a8fba32be2d7cc8 Mon Sep 17 00:00:00 2001 From: Raed Bahri Date: Sat, 24 May 2025 01:37:16 +0100 Subject: [PATCH 2/3] chore: typo --- .github/workflows/pr-checks.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml index fc12dda..398dd1d 100644 --- a/.github/workflows/pr-checks.yml +++ b/.github/workflows/pr-checks.yml @@ -1,4 +1,4 @@ -name: Branch Protection & PR Checks +name: PR Checks on: pull_request: From ecc4f32886dc2060c9d72f6a13e18dbc091532e7 Mon Sep 17 00:00:00 2001 From: Raed Bahri Date: Sat, 24 May 2025 01:38:56 +0100 Subject: [PATCH 3/3] fix: workflow --- .github/workflows/pr-checks.yml | 2 +- RELEASE_GUIDE.md | 210 -------------------------------- 2 files changed, 1 insertion(+), 211 deletions(-) delete mode 100644 RELEASE_GUIDE.md diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml index 398dd1d..c52bcc4 100644 --- a/.github/workflows/pr-checks.yml +++ b/.github/workflows/pr-checks.yml @@ -63,7 +63,7 @@ jobs: required_files=( "package.json" - "README.md" + "readme.md" "CHANGELOG.md" "LICENSE" "CONTRIBUTING.md" diff --git a/RELEASE_GUIDE.md b/RELEASE_GUIDE.md deleted file mode 100644 index 092b09a..0000000 --- a/RELEASE_GUIDE.md +++ /dev/null @@ -1,210 +0,0 @@ -# ๐Ÿš€ BlogForge Release Process Guide - -This project uses a **simplified, powerful release process** that integrates seamlessly with your existing commitizen workflow and follows best practices. - -## ๏ฟฝ Prerequisites - -### 1. GitHub Secrets Setup -Make sure you have these secrets configured in your GitHub repository: -- `NPM_TOKEN`: Your npm authentication token for publishing packages -- `GITHUB_TOKEN`: Automatically provided by GitHub Actions - -### 2. NPM Token Setup -1. Go to [npmjs.com](https://www.npmjs.com) and log in -2. Go to Profile โ†’ Access Tokens -3. Create a new **Automation** token -4. Copy the token and add it as `NPM_TOKEN` in your GitHub repository secrets -- โœ… Manual release triggers for special cases -- โœ… Version management with standard-version - -## ๐Ÿ“ Using Conventional Commits - -We use commitizen to ensure consistent commit messages. Always commit using: - -```bash -npm run commit -``` - -This will guide you through creating properly formatted commits like: -- `feat: add new blog template system` -- `fix: resolve markdown parsing issue` -- `docs: update API documentation` -- `chore: update dependencies` - -### Commit Types and Their Impact - -| Type | Description | Version Bump | Section in Changelog | -|------|-------------|--------------|---------------------| -| `feat` | New feature | Minor | ๐Ÿš€ Features | -| `fix` | Bug fix | Patch | ๐Ÿ› Bug Fixes | -| `docs` | Documentation | Patch | ๐Ÿ“š Documentation | -| `chore` | Maintenance | Patch | ๐Ÿงน Maintenance | -| `ci` | CI/CD changes | Patch | ๐Ÿงน Maintenance | -| `refactor` | Code refactoring | Patch | ๐Ÿงน Maintenance | -| `perf` | Performance improvements | Patch | ๐Ÿงน Maintenance | -| `test` | Tests | Patch | ๐Ÿงน Maintenance | - -**Breaking Changes**: Add `!` after the type (e.g., `feat!: redesign API interface`) to trigger a major version bump. - -## ๐Ÿ”„ Automatic Release Workflow - -### 1. Push to Master Triggers Release Draft - -When you push commits to the `master` branch: - -1. **Build & Test**: Code is built and linted automatically -2. **Change Detection**: System analyzes commits since last release -3. **Version Calculation**: Uses conventional commits to determine version bump -4. **Release Draft**: Creates a GitHub release draft with: - - Automatically generated changelog - - Categorized changes (Features, Bug Fixes, etc.) - - Contributor information - - Proper semantic versioning - -### 2. Publishing the Release - -To publish a release and trigger npm publication: - -1. Go to your GitHub repository -2. Navigate to **Releases** tab -3. Find the draft release -4. Review the changelog and version -5. Edit if needed, then click **"Publish release"** - -This will: -- โœ… Update `package.json` version -- โœ… Generate/update `CHANGELOG.md` -- โœ… Build the project -- โœ… Publish to npm automatically -- โœ… Push changes back to master - -## ๐ŸŽฏ Manual Release Triggers - -For special cases, you can manually trigger releases: - -### Via GitHub Actions UI - -1. Go to **Actions** tab in your repository -2. Select **"Manual Release Trigger"** workflow -3. Click **"Run workflow"** -4. Choose version bump type: - - **patch**: 0.1.10 โ†’ 0.1.11 (bug fixes) - - **minor**: 0.1.10 โ†’ 0.2.0 (new features) - - **major**: 0.1.10 โ†’ 1.0.0 (breaking changes) - - **prerelease**: 0.1.10 โ†’ 0.1.11-beta.0 (beta releases) - -### Via Command Line (Local) - -```bash -# Create and push a release -npm run release - -# Specific version bumps -npx standard-version --release-as patch -npx standard-version --release-as minor -npx standard-version --release-as major - -# Prerelease -npx standard-version --prerelease beta - -# Then push tags -git push --follow-tags origin master -``` - -## ๐Ÿ“‹ Release Checklist - -Before creating a release: - -- [ ] All tests pass -- [ ] Code is properly linted -- [ ] Documentation is up to date -- [ ] Breaking changes are documented -- [ ] Version bump is appropriate for changes - -## ๐Ÿ”ง Setup Requirements - -### GitHub Secrets - -Make sure these secrets are configured in your repository: - -1. **GITHUB_TOKEN**: Automatically provided by GitHub -2. **NPM_TOKEN**: Your npm authentication token - - Get from [npmjs.com](https://www.npmjs.com/settings/tokens) - - Use "Automation" token type - - Add in repository Settings > Secrets and variables > Actions - -### Package.json Configuration - -Your `package.json` should have: - -```json -{ - "scripts": { - "commit": "cz", - "release": "standard-version" - } -} -``` - -## ๐ŸŽจ Changelog Format - -The generated changelog follows this structure: - -```markdown -## [1.2.0] - 2024-01-15 - -### ๐Ÿš€ Features -- feat: add new blog template system (a1b2c3d) -- feat: implement draft post functionality (d4e5f6g) - -### ๐Ÿ› Bug Fixes -- fix: resolve markdown parsing issue (g7h8i9j) -- fix: correct file path handling on Windows (j1k2l3m) - -### ๐Ÿ“š Documentation -- docs: update API documentation (m4n5o6p) -- docs: add contribution guidelines (p7q8r9s) - -### ๐Ÿงน Maintenance -- chore: update dependencies (s1t2u3v) -- ci: improve build performance (v4w5x6y) - -## Contributors - -Thanks to all contributors who made this release possible! ๐ŸŽ‰ - -* @username1 -* @username2 -``` - -## ๐Ÿšจ Troubleshooting - -### Release Draft Not Created - -- Check that commits follow conventional format -- Ensure you're pushing to `master` branch -- Verify GitHub Actions are enabled - -### NPM Publish Failed - -- Check `NPM_TOKEN` secret is correct -- Verify package name is available -- Ensure version doesn't already exist - -### Version Conflicts - -- Let the workflow handle versioning automatically -- Don't manually edit `package.json` version -- Use the manual trigger if needed - -## ๐Ÿ“ž Support - -For issues with the release process: -1. Check GitHub Actions logs -2. Verify conventional commit format -3. Ensure all secrets are configured -4. Review this guide for proper workflow - ---- - -*This release system follows industry best practices and integrates seamlessly with your existing commitizen workflow.*