Skip to content
This repository has been archived by the owner on May 1, 2023. It is now read-only.

Latest commit

 

History

History
262 lines (175 loc) · 8.47 KB

CONTRIBUTING.md

File metadata and controls

262 lines (175 loc) · 8.47 KB

Contribution Guidelines

Sayyara is an open source project built for our Undergraduate Software Engineering Program's Capstone.

When contributing, whether on GitHub or in other community spaces, remember to:

  • Be respectful, civil, and open-minded
  • Before opening a new pull request or issue, try searching through the issue tracker for known issues or fixes

Below you can find some guidance on how to work on our project.

Table of Contents

  1. Getting Started
  2. Building and Running
  3. Check the Code
  4. Making Changes
  5. Testing
  6. Writing Docs
  7. Writing Code Docs
  8. Code Reviews

Getting Started

Setting up your environment

Sayyara is built and run on Node.js JavaScript Runtime. Docker is also used for the external dependencies.

  • Install the latest LTS version of Node.js
    • We recommend using a Node.js version manager like nvm or fnm
  • Install a code editor
  • Install the git version control tool
  • Install Docker

Setting up the project

Some commands will assume you have the GitHub CLI installed, if you haven't yet, consider installing it, but you can always use the Web UI if you prefer that instead.

Note: If you are a maintainer, you can skip the forking steps and work on this repository directly

In order to contribute to this project, you will need to fork the repository:

gh repo fork arkinmodi/project-sayyara

Then, clone it to your local machine:

gh repo clone <your-github-name>/project-sayyara

# Or if you prefer git
git clone https://github.com/<your-github-username>/project-sayyara

Then cd into the newly cloned directory and install the project's dependencies

npm install

Building and Running

An .env file will need to be created. A template .env.example is available to help you get setup. The default DATABASE_URL is configured to connect to the local MySQL database started using this repository's docker-compose.yml. You will need to generate a NEXTAUTH_SECRET. This secret is used by NextAuth.js to encrypt the JWT. The secret is a random unique string. One can be generated using:

openssl rand -base64 32

This project uses Bing Maps APIs and you will need to generate an API key.

This project uses Docker to start up a local MySQL database.

# Start
npm run docker:up

# Stop
npm run docker:down

This project uses Prisma as an ORM and for generating type definitions for database objects. To apply the database schema onto the MySQL database run (the database will be targeted by the DATABASE_URL in your .env):

npm run db:push

To generate the Prisma TypeScript type definitions, run:

npm install

This project uses TypeScript and Next.js.

To start a local development server on http://localhost:3000/:

npm run dev

To compile and start a production on http://localhost:3000/ (this enables the PWA functionality):

# Compile
npm run build

# Start
npm run start

Check the Code

To run all the linters on the entire code base:

npm run lint

To run the TypeScript type checking on the entire code base:

npm run lint:types

To run the ESLint lint checking on the entire code base:

npm run lint:eslint

To run the Prettier formatter on the entire code base:

npm run lint:prettier

Making Changes

Once you have made you changes, verify that the project will work (see Building and Running section) and the project meets style guidelines (see Check the Code section).

Please also create tests as deem appropriate (see Testing section). While there is not enforce code coverage metric, we aim to be as high as reasonable possible.

Every change you make should be stored in a git commit. Changes should be committed to a new local branch, which then gets pushed to your fork of the repository on GitHub.

  1. Ensure your main branch is up to date:
git switch main
git pull upstream main

# For maintainers
git pull origin main
  1. Create a new branch, based off the main branch:
git checkout -b <new-branch-name> main

# For maintainers
git checkout -b <your-github-name>/<new-branch-name> main
  1. Stage files to include in a commit:
git add <paths-to-changes-files>
  1. Create the commit:
git commit
  1. Push changes to your fork:
git push -u origin <new-branch-name>
  1. Open a pull request to merge into main. Make sure to fill out the title and body appropriately.
gh pr create --web

Testing

Testing is done using Jest. The unit test suite and integration test suite are differentiated using jest-runner-groups which requires the decoration of @group unit and @group integration, respectively, inside a comment at the top of the test file.

The integration test suite also requires a running local MySQL database. Reference the Building and Running section for instructions on how to start the local database.

To run the full test suite:

npm run test

To run just the unit test suite:

npm run test:unit

To run just the integration test suite:

npm run test:integration

To get a combined code coverage report (unit tests and integration tests), run:

npm run test:coverage

Writing Docs

The documentation is written in LaTeX and are located under the docs folder. Make changes to the .tex files. To build the LaTeX files into a pdf locally using Docker run:

# Build ALL docs
npm run build:docs

# Build a specific doc
npm run build:docs -- PS      # Problem Statement and Goals
npm run build:docs -- DevP    # Development Plan
npm run build:docs -- SRS     # Software Requirements Specification
npm run build:docs -- HazA    # Hazard Analysis
npm run build:docs -- VnVP    # Verification and Validation Plan
npm run build:docs -- MG      # Design/SoftArchitecture   Module Guide
npm run build:docs -- MIS     # Design/SoftDetailedDes  Module Interface Specification
npm run build:docs -- SystDes # Design/SystDesign  System Design
npm run build:docs -- VnVR    # Verification and Validation Report
npm run build:docs -- UGde    # User Guide
npm run build:docs -- Refl    # Reflection Report

Upon opening of a pull request, the GitHub Action pipeline will build the PDF. It is not required for you to commit a built PDF as part of your PR as the main branch pipeline will create one for you.

Writing Code Documentation (Docstrings)

The code documentation is written using TypeDoc and are written for all functions and classes. To build the HTML documentation run:

npm run build:typedoc

Code Reviews

All pull requests, include those from maintainers, require a review from another maintainer as defined in the CODEOWNERS

Credits

This document was heavily inspired by the contributing guidelines for cloudflare/wrangler2 and t3-oss/create-t3-app.