diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 00000000..8f8cbb6c --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,30 @@ +name: Lint + +on: + push: + branches: + - main + pull_request: + workflow_dispatch: + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + + - name: Setup pnpm + uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0 + with: + version: 8 + + - name: Setup Node.js + uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0 + with: + node-version: '22' + + - name: Install dependencies + run: pnpm install + + - name: Run linter + run: pnpm lint diff --git a/.github/workflows/test-deploy.yml b/.github/workflows/test-deploy.yml index 4577de44..5b8e08fc 100644 --- a/.github/workflows/test-deploy.yml +++ b/.github/workflows/test-deploy.yml @@ -1,15 +1,63 @@ -name: CI +# This job will be configured to deploy once we decide how we +# want to deploy this to npm. Until then, we will only run the test suite. +# We still need access to npm but i did email the original devs about getting +# that access. +name: Deploy +# i suggest we set this to deploy on release. on: - pull_request: push: branches: - main + workflow_dispatch: jobs: - setup: + deploy: runs-on: ubuntu-latest + # Disabled until npm permissions are set up + # Note: When enabled, this should depend on test workflow passing + if: false && github.ref == 'refs/heads/main' && github.event_name == 'push' + environment: + name: npm-publish steps: - - uses: actions/checkout@v4 - - name: Verify checkout - run: echo "Repository checked out successfully" + - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + with: + fetch-depth: 0 + + - name: Setup pnpm + uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0 + with: + version: 8 + + - name: Setup Node.js + uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0 + with: + node-version: '22' + registry-url: 'https://registry.npmjs.org' + + - name: Install dependencies + run: pnpm install + + - name: Debug installed packages + run: | + npm list --depth=0 + echo "---" + npm list prettier + + - name: Download coverage + uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0 + with: + name: coverage + path: coverage/ + + - name: Upload to Codecov + uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de # v5.5 + with: + directory: ./coverage + fail_ci_if_error: false + # Let's consider moving away from semantic-release and using a manual release strategy instead. + - name: Run semantic-release + run: pnpm semantic-release + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 00000000..3d20d4e4 --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,42 @@ +name: Run Test Suite + +on: + push: + branches: + - main + pull_request: + workflow_dispatch: + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + + - name: Setup pnpm + uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0 + with: + version: 8 + + - name: Setup Node.js + uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0 + with: + node-version: '22' + + - name: Install dependencies + run: pnpm install + + - name: Build + run: pnpm build + + - name: Run tests + run: pnpm test + env: + NODE_OPTIONS: --experimental-vm-modules + + - name: Upload coverage + uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0 + with: + name: coverage + path: coverage/ + retention-days: 7 diff --git a/.gitignore b/.gitignore index 2fd7ba65..f9cde964 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ dist # these cause more harm than good # when working with contributors +pnpm-lock.yaml package-lock.json yarn.lock pnpm-lock.yaml diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 00000000..c27f7cf3 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,222 @@ +# Development Guide + +This guide will help you get started with working on the all-contributors CLI. +We're excited to have you here! This document covers everything you need to know +about our testing setup, development workflow, and how to contribute +effectively. + +## Prerequisites + +Before you begin working on the package, make sure you have the following +installed: + +- **Node.js**: >=22.22.0 +- **Package Manager**: pnpm (version 8) + +If you don't have pnpm installed yet, you can install it globally with +`npm install -g pnpm`. + +## Getting started + +Once you've cloned the repository, getting set up is straightforward: + +1. Install pnpm: + + ```bash + pnpm install + ``` + +That's it! You're ready to start developing. + +## Testing + +All pull requests should be tested and validated before merging. Our test suite +is configured to run automatically on all pull requests using GitHub Actions. + +IMPORTANT: we are in the process of migrating from CircleCI to GitHub Actions. + +So you will see both in our configuration. + +### Testing tools + +We use a combination of tools to ensure code quality: + +- **Jest**: Our test framework, configured via `kcd-scripts` to provide sensible + defaults +- **nock**: For mocking HTTP requests when testing API interactions +- **kcd-scripts**: A helpful wrapper that provides Jest configuration and + testing utilities, so you can focus on writing tests rather than configuring + them + +### How to run tests + +You can run tests using pnpm or npm. + +#### Run all tests + +```bash +pnpm test +``` + +This command runs Jest with our project configuration from `jest.config.js`. It +runs all tests once and exits (no watch mode). This matches the behavior in CI. +It includes: + +- Test coverage collection +- Coverage thresholds (50% branches/lines/statements, 40% functions) + +**Tip**: If you want to run tests in watch mode during development (tests will +re-run automatically when files change), you can use: + +```bash +pnpm test -- --watch +``` + +#### Run validation (recommended before committing) + +```bash +pnpm validate +``` + +This is our all-in-one command that runs everything you need to clean up your +code and docs before committing: + +- Linting (ESLint) +- Type checking +- Tests +- Build verification + +**Tip**: This is the same command that runs in CI, so if `pnpm validate` passes +locally, your PR should pass CI checks. + +### Test structure + +Tests are an important part of our development workflow. + +- Test files live in `__tests__` directories right next to the source files +- For example, `src/util/__tests__/url.js` tests `src/util/url.js` +- We use Jest's standard `test()` and `expect()` APIs, so if you're familiar + with Jest, you'll feel right at home + +### Writing tests + +When you're adding new features, here's what we'd love to see: + +1. Write tests alongside your code (we find this helps us think through edge + cases) +2. Place test files in `__tests__` directories next to the code they test +3. Use `nock` for mocking HTTP requests to external APIs (it makes testing API + interactions much easier) +4. Make sure coverage thresholds are met (you can check `jest.config.js` for the + current requirements) + +## Code quality + +We maintain high code quality standards, and we've set up tools to help make +this easy for everyone. + +### Linting + +Run the linter anytime with: + +```bash +pnpm lint +``` + +We use ESLint with configuration from `kcd-scripts`, and we've customized some +rules in `package.json` to fit our project's needs. The linter helps catch +common mistakes and keeps our codebase consistent. + +### Pre-commit hooks + +We've set up Husky to run `kcd-scripts pre-commit` automatically before each +commit. This means: + +- Staged files are linted +- Code is formatted with Prettier +- Tests run on staged files + +This helps catch issues before they make it into the repository, saving everyone +time. If the pre-commit hook fails, don't worry—just fix the issues and try +committing again. + +## Building + +To build the project: + +```bash +pnpm build +``` + +This compiles the source code from `src/` to `dist/` using Babel (via +`kcd-scripts build`). The built files are what get published to npm, so it's +worth making sure the build works before pushing your changes. + +## Continuous integration + +We run tests automatically to ensure everything stays working: + +- Push to `main` branch +- Pull requests +- Manual workflow dispatch (for when you want to test things manually) + +Our CI workflow (`.github/workflows/test-deploy.yml`) does the following: + +1. Runs `pnpm validate` - This runs all our checks (lint, test, build) +2. Uploads test coverage as an artifact +3. (Deploy job is currently disabled while we finalize our release process) + +If you see a CI failure, don't panic! Check the logs—they'll tell you exactly +what went wrong, and you can usually reproduce the issue locally by running +`pnpm validate`. + +## Coverage + +We track test coverage to help ensure our codebase is well-tested. When you run +tests, coverage reports are automatically generated. + +## Development scripts + +Here are all the scripts available to you: + +- `pnpm test` - Run tests only +- `pnpm validate` - Run lint, test, and build (this is what you want to run + before committing) +- `pnpm lint` - Run the linter only +- `pnpm build` - Build the project +- `pnpm dev` - Run the CLI from source (`./src/cli.js`) - great for quick + testing +- `pnpm start` - Run the CLI from built files (`./dist/cli.js`) +- `pnpm commit` - Use commitizen for conventional commits (helps keep our commit + history clean) + +## Troubleshooting + +We've all been there—sometimes things don't work as expected. Here are some +common issues and how to fix them: + +### Tests are failing + +If your tests aren't passing, try these steps: + +- Make sure you've run `pnpm install` to install all dependencies +- Check that you're using Node.js >=22.22.0 (you can check with + `node --version`) +- Try clearing `node_modules` and reinstalling: + `rm -rf node_modules && pnpm install` + +If you're still stuck, feel free to open an issue or ask for help—we're here to +support you! + +### Coverage thresholds not met + +If you're seeing coverage threshold errors: + +- Review the coverage report in the `coverage/` directory to see what's not + covered +- Add tests for uncovered code paths +- Check `jest.config.js` for the current threshold requirements + +Remember, these thresholds are there to help us maintain quality, but they're +not meant to be a burden. If you're having trouble meeting them, reach out and +we can discuss the best approach. diff --git a/package.json b/package.json index f7d17ec5..0293f4f7 100644 --- a/package.json +++ b/package.json @@ -16,7 +16,7 @@ "add-contributor": "kcd-scripts contributors add", "build": "kcd-scripts build", "lint": "kcd-scripts lint", - "test": "kcd-scripts test", + "test": "kcd-scripts test --watchAll=false", "validate": "kcd-scripts validate", "commit": "git-cz", "start": "./dist/cli.js", diff --git a/src/generate/__tests__/__snapshots__/index.js.snap b/src/generate/__tests__/__snapshots__/index.js.snap index 0786d91c..fe26b3a0 100644 --- a/src/generate/__tests__/__snapshots__/index.js.snap +++ b/src/generate/__tests__/__snapshots__/index.js.snap @@ -1,7 +1,7 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP exports[`replace the content between the ALL-CONTRIBUTORS-LIST tags by a custom wrapper around the list of contributors contained in the "bodyContent" tag 1`] = ` -"# project +# project Description @@ -12,9 +12,9 @@ These people contributed to the project:

- Kent C. Dodds is awesome! - Divjot Singh is awesome! - Jeroen Engels is awesome! + Kent C. Dodds is awesome! + Divjot Singh is awesome! + Jeroen Engels is awesome!

@@ -23,11 +23,11 @@ These people contributed to the project: -Thanks a lot everyone!" +Thanks a lot everyone! `; exports[`replace the content between the ALL-CONTRIBUTORS-LIST tags by a table of contributors 1`] = ` -"# project +# project Description @@ -39,9 +39,9 @@ These people contributed to the project: - - - + + +
Kent C. Dodds is awesome!Divjot Singh is awesome!Jeroen Engels is awesome!Kent C. Dodds is awesome!Divjot Singh is awesome!Jeroen Engels is awesome!
@@ -51,11 +51,11 @@ These people contributed to the project: -Thanks a lot everyone!" +Thanks a lot everyone! `; exports[`replace the content between the ALL-CONTRIBUTORS-LIST tags by a table of contributors with linkToUsage 1`] = ` -"# project +# project Description @@ -67,16 +67,16 @@ These people contributed to the project: - - - + + + - @@ -88,11 +88,11 @@ These people contributed to the project: -Thanks a lot everyone!" +Thanks a lot everyone! `; exports[`replace the content between the ALL-CONTRIBUTORS-LIST tags by a table of contributors without linkToUsage 1`] = ` -"# project +# project Description @@ -104,9 +104,9 @@ These people contributed to the project:
Kent C. Dodds is awesome!Divjot Singh is awesome!Jeroen Engels is awesome!Kent C. Dodds is awesome!Divjot Singh is awesome!Jeroen Engels is awesome!
- - Add your contributions + + + Add your contributions
- - - + + +
Kent C. Dodds is awesome!Divjot Singh is awesome!Jeroen Engels is awesome!Kent C. Dodds is awesome!Divjot Singh is awesome!Jeroen Engels is awesome!
@@ -116,11 +116,11 @@ These people contributed to the project: -Thanks a lot everyone!" +Thanks a lot everyone! `; exports[`split contributors into multiples lines when there are too many 1`] = ` -"# project +# project Description @@ -132,15 +132,15 @@ These people contributed to the project: - - - - - + + + + + - - + +
Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!
Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!
@@ -150,11 +150,11 @@ These people contributed to the project: -Thanks a lot everyone!" +Thanks a lot everyone! `; exports[`split contributors into multiples lines when there are too many with linkToUsage 1`] = ` -"# project +# project Description @@ -166,22 +166,22 @@ These people contributed to the project: - - - - - + + + + + - - + + - @@ -193,11 +193,11 @@ These people contributed to the project: -Thanks a lot everyone!" +Thanks a lot everyone! `; exports[`validate if cell width attribute is floored correctly 1`] = ` -"# project +# project Description @@ -209,9 +209,9 @@ These people contributed to the project:
Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!
Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!
- - Add your contributions + + + Add your contributions
- - - + + +
Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!Kent C. Dodds is awesome!
@@ -221,5 +221,5 @@ These people contributed to the project: -Thanks a lot everyone!" +Thanks a lot everyone! `; diff --git a/src/init/__tests__/__snapshots__/add-contributors-list.js.snap b/src/init/__tests__/__snapshots__/add-contributors-list.js.snap index c528a5a1..29e19484 100644 --- a/src/init/__tests__/__snapshots__/add-contributors-list.js.snap +++ b/src/init/__tests__/__snapshots__/add-contributors-list.js.snap @@ -1,7 +1,7 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP exports[`create contributors section if content is empty 1`] = ` -" + ## Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): @@ -13,11 +13,11 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d -This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!" +This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! `; exports[`create contributors section if it is absent 1`] = ` -"# project +# project Description ## Contributors ✨ @@ -31,11 +31,11 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d -This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!" +This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! `; exports[`insert list under contributors section 1`] = ` -"# project +# project Description @@ -46,5 +46,5 @@ Description -" + `;