Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
208 lines (154 loc) · 7.91 KB

CONTRIBUTING.md

File metadata and controls

208 lines (154 loc) · 7.91 KB
Raw

Contributing to Real Dev Squad API

Getting Started

Instructions for initial setup can be found in the README.

Pnpm Command Reference

pnpm install

Installs all dependencies listed in the root package.json.

pnpm build

Compiles TypeScript + allowJs sources to dist/ via tsc (tsconfig.json: outDir: dist). typescript is a devDependency, so run this before any pnpm prune --prod. Required before pnpm start (start runs node ./dist/server.js and does not rebuild).

pnpm dev

Starts the server in dev mode with ts-node-dev (no dist/ build needed).

pnpm test

The script associated with pnpm test will run all tests that ensures that your commit does not break anything in the repository. This will run the lint, integration and unit tests.

pnpm test-unit / pnpm test-integration

Run only unit or only integration tests (see scripts/tests/testUnit.sh / testIntegration.sh).

pnpm tdd:watch

Run TDD in watch mode for files listed in scripts/tests/tdd-files-list.txt.

pnpm lint

Runs the lint checks in the project.

pnpm lint-fix

Runs lint checks and auto-fixes what can be fixed.

pnpm validate-setup

Runs the test for checking local development setup is working properly or not.

Project Structure

The following project structure should be followed:

|-- website-backend
    |-- config
    |   |-- custom-environment-variables.js
    |   |-- default.js
    |   |-- development.js
    |   |-- production.js
    |   |-- staging.js
    |   |-- test.js
    |-- controllers
    |   |-- health.js
    |   |-- // Controller files concerning function on a similar entity
    |-- logs
    |   |-- // log files
    |-- middlewares
    |   |-- // individual middleware files to be required on server start or in the route middleware
    |-- models
    |   |-- // Files consisting of the individual table/collection config and wrapper interaction functions
    |-- routes
    |   |-- index.js // routes files separated by their first path string
    |   |-- auth.js // the individual routes files should contain the OPEN API JSDOC reference
    |-- services
    |   |-- authService.js // Files using any 3rd party library/service or providing any secific service in the project
    |-- scripts // Standalone scripts
    |-- test
    |   |-- fixtures
    |   |   |-- auth
    |   |       |-- githubUserInfo.js
    |   |-- integration // Integration tests
    |   |   |-- auth.test.js
    |   |-- unit // Unit tests
    |   |   |-- middlewares
    |   |   |-- services
    |   |-- utils // Utility functions to be used while testing
    |-- utils // Files containing utility functions
    |    |-- logger.js
    |-- .github
    |   |-- workflows
    |       |-- // Github actions files
    |-- .husky // git hooks (pre-commit runs `pnpm lint`)
    |-- .gitignore
    |-- .*rc, .*js, .*json, .*yml // config files for dependencies
    |-- CONTRIBUTING.md
    |-- README.md
    |-- CHANGELOG.md
    |-- app.js
    |-- pnpm-workspace.yaml
    |-- pnpm-lock.yaml
    |-- package.json
    |-- server.js // Contains server start logic

Generating Authentication Token

  • Run the project locally, make sure the server is listening to requests
  • Navigate to https://github.com/login/oauth/authorize?client_id=<GITHUB_CLIENT_ID>
  • Authorize the application
  • Once authorized, check browser's cookies section. Copy the value of the cookie named rds-session (rds-session-development for development mode).
  • Use the cookie for authenticated routes in the API.
  • For non-production environments, authentication is also supported with the Authorization header.
  • Authorization header: Authorization: Bearer <token>

Production login:

https://api.realdevsquad.com/auth/github/login

Production login - Cookie:

rds-session

Staging login:

https://staging-api.realdevsquad.com/auth/github/login

Staging login - Cookie:

rds-session-staging

Testing Guidelines

  • Libraries used in testing in the project:
    • mocha: Test framework
    • chai: Assertion library
    • sinon: JavaScript test spies, stubs and mocks
    • nock: HTTP requests mocking
  • The test suite uses Firebase Local Emulator Suite for running firestore for tests(documentation).
  • Pre-requisites:
    • Node.js 26.8.1 (installed automatically by pnpm, see README).
    • Java version 21 or higher (required by firebase-tools 15+).

Using Firebase Emulator Locally

  • Firebase Local Emulator Suite can be used locally as the DB for the project
  • Pre-requisites:
    • Node.js 26.8.1 (installed automatically by pnpm, see README).
    • Java version 21 or higher (required by firebase-tools 15+).
  • Run: npx firebase emulators:start
  • The emulator will run and display the url you can access it on.
  • You can view the emulator UI at: http://localhost:4000
  • To run the application with using firebase emulator, run the following command(docs):
export FIRESTORE_EMULATOR_HOST="localhost:<Firebase emulator PORT>"

Running test scripts on Windows

  • Git Bash is recommended for running test scripts on Windows.
  • Run pnpm test-integration for running integration tests.
  • Run pnpm test-unit for running unit tests.
  • Make sure the server is not running.
  • Make sure to close the emulator window after running the tests in order to avoid the blocking of the port for the next tests to run.
  • For e.g - After running the integration tests, close the emulator window and then run the command for unit tests.

Pre-commit Hook

This project uses husky to run a pre-commit hook that automatically lints your changes before each commit. The hook runs pnpm lint.

Husky is set up automatically when you run pnpm install (via the prepare script in package.json). No manual configuration is needed.

If you want to bypass the hook for a specific commit (not recommended), you can use:

git commit --no-verify

Pull request guidelines

  • Ensure that the tests pass locally before raising a PR.
  • All pull requests should have base as the develop branch.
  • Every pull request should have associated issue(s) on our issue tracker.
  • For any non-trivial fixes and features, unit and integration tests must be added. The PR reviewer should not approve/merge PR(s) that lack these.
  • The PR(s) should be merged only after the CI passes.

Certain issues you may face while running the tests:

  • Java version is below 21 (firebase-tools no longer supports Java version before 21)
  • When we run pnpm test, it runs both the unit and integration tests (in this order). So after the unit tests are done, the java process is not killed automatically and when our integration test run it gives error.
  • Error: connect ECONNREFUSED ::1:8081

Possible solutions for above issues (in particular order):

  • Java version 21 or above is needed for firebase-tools version >= 15
  • Either manually kill the java process after unit tests are done or run both the tests separately by running the test commands.
  • Add 'host : 0.0.0.0' to both firestore and ui object in firebase.json file if it is not added. for more info refer this : #918