Skip to content

Latest commit

 

History

History
187 lines (127 loc) · 5.98 KB

CONTRIBUTING.md

File metadata and controls

187 lines (127 loc) · 5.98 KB
Raw

How To Contribute

Local development

Prerequisites

Steps

  1. Fork the repository (https://help.github.com/articles/fork-a-repo/)

  2. Clone the repository to your local machine (https://help.github.com/articles/cloning-a-repository/)

    git clone [email protected]:[username]/rsschool-app.git

  3. Navigate into the directory where you've cloned the source code and install NPM dependencies

    cd rsschool-app
npm install

  4. Create a branch for your feature

    git checkout -b feature-x master

  5. The application requires a connection to a Postgres database. Here is how to get test database running locally:

    Run a Postgres Database locally using Podman & podman-compose

    npm run db:up

    Restore a test database snapshot

    npm run db:restore

    If you are done with development, stop the database;

    npm run db:down

  6. Run the application in development mode with live reload:

    npm start

  7. Do hacking 👩‍💻👨‍💻

  8. You could specify any environment variable during development using .env file. Make a copy of server/.env.example and nestjs/.env.example and rename it to server/.env or nestjs/.env respectively. We support it via dotenv package. More information about usage here: https://github.com/motdotla/dotenv

  9. By default locally, you will be logged with admin access. If you want to change it, need to set RSSCHOOL_AUTH_DEV_ADMIN to false in nestjs/.env file

    IMPORTANT: Never commit changes to .env file

  10. Do not forget to write unit-tests for your feature following Unit-Tests Style Guide. We use Jest for unit-tests.

  11. Write end-to-end tests for your feature if applicable. Please see client/specs directory for more information. We use Playwright for end-to-end tests. You can run them using npm run test:e2e command and they supposed to work against test database snapshot.

  12. Make sure tests, lints pass and code formatted properly (they'll be run on a git pre-commit hook too)

    npm test
npm run lint
npm run pretty

  13. Commit your changes using a descriptive commit message that follows our Commit Message Conventions

    git commit -m "feat: implement feature X"

  14. Push your branch to GitHub:

    git push origin feature-x

  15. Create a pull request. We support "feature branch" deployments. If you want to deploy your pull request, please add deploy label during creation.

API client generation

We use OpenAPI Generator to generate API client for NestJS API. Here are steps how to do it:

  • Make sure database is running locally

  • Navigate to ./nestjs

  • Run

    npm run openapi

  • Commit updated files (/client/src/api/* and ./nestjs/src/spec.json)

NOTE: in case of problems with running openapi you might need to install Java or use some other way from OpenAPI Generator Installation docs

Database Migrations

If you made changes to DB models, you need to create a DB migration. Here are steps how to do it

  1. Go to /server
  2. Run npm run typeorm:migration:generate src/migrations/{MigrationName} where {MigrationName} is your migration name.
  3. Import your migration to migrations array at ./server/src/migrations/index.ts
  4. Commit and push your changes

See more about TypeORM migrations at official docs Migrations

Pull Requests

  • Check how to create a Pull Request
  • Send a pull request to master branch
  • Fill template
  • Write a meaningful description
  • Include screenshots and animated GIFs in your pull request whenever possible
  • Add deploy label if you want to test your changes

Style Guides

Git Commit Messages

  • Use Conventional Commits format
  • Allowed Types:
    • build: - changes that affect the build system or external dependencies (example scopes: npm, webpack)
    • ci: - changes to our CI configuration files and scripts (example scopes: drone)
    • docs: - documentation only changes
    • feat: - a new feature
    • fix: - a bug fix
    • perf: - a code change that improves performance
    • refactor: - a code change that neither fixes a bug nor adds a feature
    • style: - changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
    • test: - adding missing tests or correcting existing tests
  • Use the present tense ("add feature" not "added feature")
  • Use the imperative mood ("move cursor to..." not "moves cursor to...")
  • Limit the first line to 72 characters or less
  • Reference issues and pull requests liberally after the first line

TypeScript Style Guide

We use Prettier for TypeScript formatting. Please run the following command before your commit:

npm run format

For your convenience, you can integrate Prettier into your favorite IDE (https://prettier.io/docs/en/editors.html)

Unit-Tests Style Guide

  • Name spec file by adding .test to the name of tested file.

Example:

foo.ts
foo.test.ts // test file for foo.ts
  • Treat describe as a noun or situation.
  • Treat it as a statement about state or how an operation changes state.

Example:

describe('Header', () => {
  it('shows username', () => {
    //...
  });

  it('shows logout button', () => {
    //...
  });
});