Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
342 lines (221 loc) · 11.2 KB

CONTRIBUTING.md

File metadata and controls

342 lines (221 loc) · 11.2 KB

Contributing

We welcome and appreciate all contributions from the community. By contributing to Study Timer, you agree to abide by the code of conduct.

Table of Contents

How Can I Contribute?

Bug Reports

Before creating a bug report please check to see if it has already been reported. If the issue is closed, please open a new issue and link it to the original issue.

When creating a bug report, please fill out the template provided.

Feature Request

Before creating a feature request, please check to see if it has already been requested.

When creating a feature request, please fill out the template provided.

Documentation

The documentation for this project are files that end with .md extension.

If you would like to improve the documentation in any of these areas, please open an issue if there isn't one already to discuss what you would like to improve. Then submit a pull request to this repository.

Code

Unsure of where to begin contributing to Study Timer? You can start by looking through the issues labeled good-first-issue and help-wanted. You can also start by contributing to the project documentation (e.g files with extension .md).

For instructions on setting up your environment, see the setup instructions in this document.

Setup

If you don't already have Git installed, install it first. You will need it to contribute. You will also need to install Node and npm.

Installation

  1. Fork the Study Timer repository.
  2. Open a terminal, or "Git Bash" on Windows.
  3. Use cd to move to the directory that you want to work in.
  4. Clone your repository.
  5. Configure the remote repository for your fork.
  6. Install dependencies: 
    npm install
  7. Open the Study Timer folder in your favorite editor. If you don't have one, try Visual Studio Code

Getting Started

Please complete Setup first and then return here.

1. Create enviornment variables

  1. Create .env.local
cd studytimer.io
touch .env.local
  1. Add the following variables in .env.local
VITE_APP_NAME="Study Timer"
VITE_APP_TITLE="Study Timer | Online Pomodoro Focus Timer | Code Cause"

Note: Non-sensetive enviorment variables used client-side must have prefix _VITE__ and added to vite-end.d.ts and .env.local before usage. For more information see Vite docs: Env Variables and Modes.

2. Enable HTTPS for development

In this case a self-signed certificate will be sufficent (in our opinion). Granted, there are other forms of certificates, such as locally trusted certificates generated with tools like mkcert or certificates issued by a certificate authority (CA) - depending on the development or testing scenario these may be more appropriate.

  1. Create folder (ssl/ or tls/) in project directory to place the created private key and public certificate beforehand:
cd studytimer.io
mkdir ssl # or mkdir tls
  1. Use the following command to create a private key and public certificate with OpenSSL:

Replace placeholders <KEY_FILE_NAME> and <CERT_FILE_NAME> with the name of the files of your choosing.

openssl req -newkey rsa:2048 -nodes -keyout ssl/<KEY_FILE_NAME>.key -x509 -days 365 -out ssl/<CERT_FILE_NAME>.crt

Next, you will see several prompts asking for information in order to create your private key and public certificate.

  1. create .env.development.local
cd studytimer.io
touch .env.development.local
  1. Add the following variables in .env.development.local and replace values HTTPS_CERT and HTTPS_KEY with the path of your private key and public certificate.
HTTPS_CERT="ssl/<CERT_FILE_NAME>.crt" # or tls/<CERT_FILE_NAME>.crt
HTTPS_KEY="ssl/<KEY_FILE_NAME>.key" #or tls/<KEY_FILE_NAME>.key

Helpful resources and guides regarding SSL/TLS and certficates:

Linting, Formating, Building, and Testing

Once you have cloned Study Timer and completed Setup, you can lint, format, build, and test the code from your terminal.

Linting

To lint the code, run:

npm run lint

Lint Fix

To lint and fix eslint errors in the code, run:

npm run lint:fix

This will start eslint and check all files for stylistic problems. See eslint.config.js file for project config and rules.

Formating

To format the code, run:

npm run format

Formatting And Lint Fix

To format and fix eslint errors in the code, run:

npm run flf

Building

To compile the Study Timer source, run:

npm run build

Using Vite, this will start the TypeScript compiler and output the bundled JavaScript to the dist folder.

Testing

To validate any changes you have made in all test files, run:

npm run test

To validate any changes you made in a specifc file, run:

npm run test <./folder-path-name/file-name>

To run code coverage, run:

npm run coverage

This will run all tests and output a detailed interactive HTML report, which will be generated in the ./coverage directory (by default), which can be viewed in a web browser.

Coverage percentage requirement for the following thresholds in order for build to succeed:

Threshold Type Required Coverage (%)
Line Coverage 80%
Branch Coverage 70%
Function Coverage 75%
Statement Coverage 80%

Pull Request

Once you have finished working on an issue or feature, you can submit a pull request to have your changes merged into the Study Timer repository and included in the next release.

Please do not change the project version number in a pull request.

Note: We squash commits into a single commit before merging any PRs, so please do not squash commits while reviewing or during PR creation.

Submitting a Pull Request

Before you submit your Pull Request (PR) consider the following:

  1. Search for an open or closed PR that relates to your submission. You don't want to duplicate existing efforts.

  2. Be sure that an issue describes the problem you're fixing, or documents the design for the feature you'd like to add. Discussing the design upfront helps to ensure that we're ready to accept your work.

  3. Skip this step if you have completed Setup. Otherwise, please complete it first and then return here.

  4. In your forked repository, make your changes in a new git branch:

    git checkout -b my-fix-branch-issue-id main

    Note: Using an issue-id suffix is optional; however, referencing an issue in the PR branch name is encouraged.

  5. Create your patch, including appropriate test cases.

  6. Run the tests and ensure no linting errors.

  7. Stage and commit your changes using a descriptive commit message.

    git add .
git commit -m "Implement fix from issue-123"

    Note: Keeping your commits small and meaningul is encouraged.

    Note: Please write commit messages following the Conventional Commits specification, particularly by using a commit message with a scope.

  8. Push your branch to your remote fork:

    git push -u origin my-fix-branch-issue-id

  9. In GitHub, send a pull request to Code-Cause-Collective/studytimer.io:main.

Reviewing a Pull Request

Community Leaders reserves the right not to accept pull requests from community members who haven't been good citizens of the community. Such behavior includes not following the code of conduct.

Addressing Review Feedback

If we ask for changes via code reviews then:

  1. Make the required updates to the code.

  2. Re-run tests to ensure tests are still passing.

  3. Commit your changes as usual and push them to your feature branch (this will automatically update your Pull Request):

    git add .
git commit -m "Address review feedback"
git push origin my-fix-branch-issue-id

That's it! Thank you for your contribution!

After Pull Request Merged

After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:

  • Delete the remote branch on GitHub either through the GitHub web UI or your local terminal as follows:

    git push origin --delete my-fix-branch-issue-id

  • Check out the main branch:

    git checkout main -f

  • Delete the local branch:

    git branch -D my-fix-branch-issue-id

Keeping Fork Synced with Upstream

  • Update your local main with the latest changes from upstream:

    git pull --ff upstream main

  • Fetch the latest changes from upstream:

    git fetch upstream

  • Update your local branch with latest changes from upstream:

    git fetch upstream && git rebase upstream/main

Resources