monkeytypegame/monkeytype
1
1
Fork 0
mirror of https://github.com/monkeytypegame/monkeytype.git synced 2025-11-08 05:03:39 +08:00
Code Issues Projects Releases Packages Wiki Activity

Add CONTRIBUTING_BASIC.md and CONTRIBUTING_ADVANCED.md (#2946) matthew-kwan

Browse source 
* Add CONTRIBUTING_BASIC.md and CONTRIBUTING_ADVANCED.md

* Update screenshot to correct radio option

* Fix type in CONTRIBUTING_BASIC.md

* Update CONTRIBUTING_BASIC.md

* Update CONTRIBUTING.md and CONTRIBUTING_ADVANCED.md

* reordered sections

* slight change

* Fixed table of contents

* fixed table of contents

* table of contents fix

Co-authored-by: Jack <jack@monkeytype.com>
This commit is contained in:
Matthew Kwan 2022-05-08 00:25:19 -07:00 • committed by Miodec
parent cdbc0bf770
commit bba59f1adb
3 changed files with 208 additions and 100 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

108
CONTRIBUTING.md
View file

@ -3,13 +3,7 @@
### **Table of Contents**
- [Getting Started](#getting-started)
- [Prerequisites](#prerequisites)
- [Text Editor](#text-editor)
- [Git](#git)
- [NodeJS and NPM](#nodejs-and-npm)
- [Firebase](#firebase)
- [Mongo Setup](#mongo-setup)
- [Building and Running Monkeytype](#building-and-running-monkeytype)
- [How to Contribute](#how-to-contribute)
- [Standards and Guidelines](#standards-and-guidelines)
- [Theme Guidelines](#theme-guidelines)
- [Language Guidelines](#language-guidelines)
@ -20,103 +14,17 @@
When contributing to Monkeytype, it's good to know our best practices, tips, and tricks. First, Monkeytype is written in ~~JavaScript~~ TypeScript, CSS, and HTML (in order of language usage within the project); thus, we assume you are comfortable in these languages or have basic knowledge of them. Our backend is in NodeJS and we use MongoDB to store our user data. Firebase is used for authentication. Furthermore, we use Prettier to format our code.
## Prerequisites
## How to Contribute
While most contributions don't require that you install dependencies, there are a few tools you will need to be able to run the project (this is useful and almost always necessary for tasks like creating features and fixing bugs; running the project is also useful if you are contributing a theme and want to view it on the site before you contribute it). You will need a computer with a stable internet connection, a text editor, Git, Firebase, and NodeJS with version 16.13.2.
We have two separate contribution guides based on what you're looking to contribute. If you're simply looking to help us augment our language or quotes data, please refer to [CONTRIBUTING_BASIC.md](./CONTRIBUTING_BASIC.md). This guide will go over how to do so easily, and without the need to set up a local development server.
#### Text Editor
If you are not a developer and wish to contribute themes, new languages, or quotes, having a text editor will make contributions _much_ easier. To make complex edits without installing anything, we recommend using GitHub's VS Code web editor. In your fork of Monkeytype (fork it first), go to the `Code` tab of the repo and press <kbd>.</kbd>(the period/dot key). This will open up the repo in an online VS Code instance you can use to edit files in the browser. Once you are done making your changes, go to the Source Control tab in the activity bar with <kbd>Ctrl/Cmd + Shift + G</kbd>, click the `+` next to the files you've changed to stage them, type a brief message summarizing the changes made in the commit, and press <kbd>Ctrl/Cmd + Enter</kbd> to commit your changes to your fork. Finally, send a pull request to the Monkeytype repository when you are ready.
#### Git
Git is optional but we recommend you utilize it. Monkeytype uses the Git source control management (SCM) system for its version control. Assuming you don't have experience typing commands in the command line, we suggest installing [Sourcetree](https://www.sourcetreeapp.com/). You will be able to utilize the power of Git without needing to remember any cryptic commands. Using a Git client such as Sourcetree won't give you access to the full functionality of Git, but provides an easy to understand graphical user interface (GUI). Once you have downloaded Sourcetree, run the installer. While installing Sourcetree, keep your eyes peeled for the option to also install Git with Sourcetree. This is the option you will need to look for in order to install Git. **Make sure to click yes in the installer to install Git with Sourcetree.**
#### NodeJS and NPM
To install NodeJS, navigate to the NodeJS [website](https://nodejs.org/en/) and download the `16.13.2 LTS`.
Alternatively, if you use `nvm` then you can run `nvm install` and `nvm use` (you might need to specify the exact version) to use the version of Node.js in the `.nvmrc` file (if you use Windows, use [nvm-windows](https://github.com/coreybutler/nvm-windows)).
#### Firebase
1. Create a Firebase account if you already haven't done so.
1. [Create a new Firebase project.](https://console.firebase.google.com/u/0/)
- The project name doesn't matter, but the name `monkeytype` would be preferred.
- Google Analytics is not necessary.
1. Run `npm install -g firebase-tools` to install the Firebase Command Line Interface.
1. Run `firebase login` on your terminal to log in to the same google account you just used to create the project.
1. Git clone this project.
- IMPORTANT: If you are on Windows, run `git config --global core.autocrlf false` before-hand to prevent CRLF errors.
1. Within the `frontend` directory, duplicate `.firebaserc_example`, rename the new file to `.firebaserc` and change the project name of default to the firebase project id you just created.
- If `.firebaserc_example` does not exist after cloning, create your own with:
```.firebaserc
{
"projects": {
"default": "your-firebase-project-id"
}
}
```
- Run `firebase projects:list` to find your firebase project id.
1. Within the `frontend/src/ts/constants` directory, duplicate `firebase-config-example.ts`, rename it to `firebase-config.ts` and paste in your firebase config
- To find it, go to the Firebase console
- Navigate to `Project Settings > General > Your apps`
- If there are no apps in your project, create a new web app
- In the `SDK setup and configuration` section, select `npm`
- The Firebase config will be visible below
1. Enable Firebase Authentication (optional)
- In the Firebase console, go to `Authentication > Sign-in method`
- Click on `Email/Password`, enable it, and save
- Click on `Google`, add a support email and save
1. Generate a Firebase Admin private key (optional, only needed if you want to work on the backend)
- In your Firebase console, go to Project Settings > Service Accounts
- Click "Generate New Private Key"
- Save as `serviceAccountKey.json` inside the `backend/credentials/` directory.
#### Backend (optional)
Follow these steps if you want to work on anything involving the database/account system. Otherwise, you can skip this section.
1. Inside the backend folder, copy `example.env` to `.env` in the same directory.
2. Setup the database server
| Local Server | Docker (recommended) |
| --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. Install [MongoDB Community Edition](https://docs.mongodb.com/manual/administration/install-community/) and ensure that it is running | <ol><li>Install [Docker](http://www.docker.io/gettingstarted/#h_installation) on your machine</li><li>Run `docker-compose up` from the `./backend` directory.</li></ol> |
3. (Optional) Install [MongoDB-compass](https://www.mongodb.com/try/download/compass?tck=docs_compass). This tool can be used to see and manipulate your data visually.
1. To connect, type `mongodb://localhost:27017` in the connection string box and press connect. The monkeytype database will be created and shown after the server is started.
## Building and Running Monkeytype
Once you have completed the above steps, you are ready to build and run Monkeytype.
1. Run `npm run install-all` in the project root to install all dependencies.
- If you are on Windows, use `npm run install-windows`.
- If neither works, you will have to run `npm install` in root, frontend, and backend directories.
2. Run `npm run dev` (`npm run dev-fe` if you skipped the mongo section) to start a local dev server on [port 5000](http://localhost:5000). It will watch for changes and rebuild when you edit files in `src/` or `public/` directories. Note that rebuilding doesn't happen instantaneously so be patient for changes to appear. Use <kbd>Ctrl+C</kbd> to kill it.
**Mac Users:** If you get 403 Forbidden errors while trying to access the local server, go into System Preferences > Sharing and disable AirPlay Receiver - it also runs on port 5000 and takes priority, causing 403 errors.
If you're looking to make deeper code changes that affect functionality, or will require screenshots of the changes, please refer to [CONTRIBUTING_ADVANCED.md](./CONTRIBUTING_ADVANCED.md).
## Standards and Guidelines
Code style is enforced by [Prettier](https://prettier.io/docs/en/install.html), which automatically runs every time you make a commit (`git commit`) (if you've followed the above instructions properly).
Below are a set of general guidelines for different types of changes.
We recommend following the guidelines below to increase your chances of getting your change accepted.
#### Theme Guidelines
### Theme Guidelines
<!-- TODO: add screenshots to provide examples for dos and don'ts -->
@ -129,7 +37,7 @@ Before submitting a theme make sure...
(If you want to contribute themes but don't know how, check [THEMES.md](./THEMES.md))
#### Language Guidelines
### Language Guidelines
- Do not include swear words
- Ensure that your contribution meets JSON standards (no trailing comma at the end of a list)
@ -138,7 +46,7 @@ Before submitting a theme make sure...
(If you want to contribute languages but don't know how, check [LANGUAGES.md](./LANGUAGES.md))
#### Quote Guidelines
### Quote Guidelines
- Do not include content that contains any libelous or otherwise unlawful, abusive or obscene text.
- Ensure that your contribution meets JSON standards (no trailing comma at the end of a list)

108
CONTRIBUTING_ADVANCED.md Normal file
View file

@ -0,0 +1,108 @@
# Contributing - Advanced
### **Table of Contents**
- [Prerequisites](#prerequisites)
- [Git](#git)
- [NodeJS and NPM](#nodejs-and-npm)
- [Firebase](#firebase)
- [Backend (optional)](#backend-optional)
- [Building and Running Monkeytype](#building-and-running-monkeytype)
- [Standards and Guidelines](#standards-and-guidelines)
- [Questions](#questions)
## Prerequisites
This contribution guide is for cases in which you need to test the functionality of your changes, or if you need to take screenshots of your changes. You will need a computer with a stable internet connection, a text editor, Git, Firebase, and NodeJS with version 16.13.2. There are some additional requirements depending on what you're looking to contribute, such as Mongo and Docker for the backend. Read the below sections to understand how to setup each of these tools.
#### Git
Git is optional but we recommend you utilize it. Monkeytype uses the Git source control management (SCM) system for its version control. Assuming you don't have experience typing commands in the command line, we suggest installing [Sourcetree](https://www.sourcetreeapp.com/). You will be able to utilize the power of Git without needing to remember any cryptic commands. Using a Git client such as Sourcetree won't give you access to the full functionality of Git, but provides an easy to understand graphical user interface (GUI). Once you have downloaded Sourcetree, run the installer. While installing Sourcetree, keep your eyes peeled for the option to also install Git with Sourcetree. This is the option you will need to look for in order to install Git. **Make sure to click yes in the installer to install Git with Sourcetree.**
#### NodeJS and NPM
To install NodeJS, navigate to the NodeJS [website](https://nodejs.org/en/) and download the `16.13.2 LTS`.
Alternatively, if you use `nvm` then you can run `nvm install` and `nvm use` (you might need to specify the exact version) to use the version of Node.js in the `.nvmrc` file (if you use Windows, use [nvm-windows](https://github.com/coreybutler/nvm-windows)).
#### Firebase
1. Create a Firebase account if you already haven't done so.
1. [Create a new Firebase project.](https://console.firebase.google.com/u/0/)
- The project name doesn't matter, but the name `monkeytype` would be preferred.
- Google Analytics is not necessary.
1. Run `npm install -g firebase-tools` to install the Firebase Command Line Interface.
1. Run `firebase login` on your terminal to log in to the same google account you just used to create the project.
1. Git clone this project.
- IMPORTANT: If you are on Windows, run `git config --global core.autocrlf false` before-hand to prevent CRLF errors.
1. Within the `frontend` directory, duplicate `.firebaserc_example`, rename the new file to `.firebaserc` and change the project name of default to the firebase project id you just created.
- If `.firebaserc_example` does not exist after cloning, create your own with:
```.firebaserc
{
"projects": {
"default": "your-firebase-project-id"
}
}
```
- Run `firebase projects:list` to find your firebase project id.
1. Within the `frontend/src/ts/constants` directory, duplicate `firebase-config-example.ts`, rename it to `firebase-config.ts` and paste in your firebase config
- To find it, go to the Firebase console
- Navigate to `Project Settings > General > Your apps`
- If there are no apps in your project, create a new web app
- In the `SDK setup and configuration` section, select `npm`
- The Firebase config will be visible below
1. Enable Firebase Authentication (optional)
- In the Firebase console, go to `Authentication > Sign-in method`
- Click on `Email/Password`, enable it, and save
- Click on `Google`, add a support email and save
1. Generate a Firebase Admin private key (optional, only needed if you want to work on the backend)
- In your Firebase console, go to Project Settings > Service Accounts
- Click "Generate New Private Key"
- Save as `serviceAccountKey.json` inside the `backend/credentials/` directory.
#### Backend (optional)
Follow these steps if you want to work on anything involving the database/account system. Otherwise, you can skip this section.
1. Inside the backend folder, copy `example.env` to `.env` in the same directory.
2. Setup the database server
| Local Server | Docker (recommended) |
| --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <ol><li>Install [MongoDB Community Edition](https://docs.mongodb.com/manual/administration/install-community/)</li><li>Make sure it is running</li></ol> | <ol><li>Install [Docker](http://www.docker.io/gettingstarted/#h_installation) on your machine</li><li>Run `docker-compose up` from the `./backend` directory</li></ol> |
3. (Optional) Install [MongoDB-compass](https://www.mongodb.com/try/download/compass?tck=docs_compass). This tool can be used to see and manipulate your data visually.
1. To connect, type `mongodb://localhost:27017` in the connection string box and press connect. The monkeytype database will be created and shown after the server is started.
## Building and Running Monkeytype
Once you have completed the above steps, you are ready to build and run Monkeytype.
1. Run `npm run install:all` in the project root to install all dependencies.
- If you are on Windows, use `npm run install-windows`.
- If neither works, you will have to run `npm install` in root, frontend, and backend directories.
2. Run `npm run dev` (`npm run dev-fe` if you skipped the mongo section) to start a local dev server on [port 5000](http://localhost:5000). It will watch for changes and rebuild when you edit files in `src/` or `public/` directories. Note that rebuilding doesn't happen instantaneously so be patient for changes to appear. Use <kbd>Ctrl+C</kbd> to kill it.
**Mac Users:** If you get 403 Forbidden errors while trying to access the local server, go into System Preferences > Sharing and disable AirPlay Receiver - it also runs on port 5000 and takes priority, causing 403 errors.
## Standards and Guidelines
Code style is enforced by [Prettier](https://prettier.io/docs/en/install.html), which automatically runs every time you make a commit (`git commit`) (if you've followed the above instructions properly).
We recommend following the guidelines below to increase your chances of getting your change accepted.
## Questions
If you have any questions, comments, concerns, or problems let me know on [GitHub](https://github.com/Miodec), [Discord](https://discord.gg/monkeytype) in the `#development` channel, or ask a question on Monkeytype's [GitHub discussions](https://github.com/monkeytypegame/monkeytype/discussions) and a contributor will be happy to assist you.

92
CONTRIBUTING_BASIC.md Normal file
View file

@ -0,0 +1,92 @@
# Contributing - Basic
### **Table of Contents**
- [Basic Contributions](#basic-contributions)
- [Prerequisites](#prerequisites)
- [Contributing](#contributing)
- [Forking Monkeytype](#forking-monkeytype)
- [Making a Change](#making-a-change)
- [Creating a Pull Request](#creating-a-pull-request)
- [Merging a Pull Request](#merging-a-pull-request)
- [Questions](#questions)
### Basic Contributions
This file details how to create basic contributions to Monkeytype purely through the use of the Github web UI. This means you will set up a local development environment of any kind. All you'll need is a browser that can access Github and an account.
Given the above, you should only be using this guide if you plan on doing changes that do no impact the functionality of the application. Examples of such cases would be translation fixes, language additions, or quote additions.
For all other changes, please refer to [CONTRIBUTING_ADVANCED.md](./CONTRIBUTING_ADVANCED.md) to learn how to setup the necessary tools to develop on your local environment.
### Prerequisites
You must have a browser that can access Github, and possess an account. Once you have those two things, you're ready to move on to making your contribution!
The steps for basic contributions are showcased splendidly in [this youtube video](https://www.youtube.com/watch?v=nT8KGYVurIU), so I highly recommend giving it a watch.
## Contributing
### Forking Monkeytype
First you will have to make a personal copy of the Monkeytype repository, also known as "forking". Go to the [Monkeytype repo](https://github.com/monkeytypegame/monkeytype/) and then click the "fork" button.
<img width="1552" alt="Screenshot showing location of the fork button on GitHub." src="https://user-images.githubusercontent.com/83455454/149194972-23343642-7a1f-4c0c-b5f2-36f4b39a2639.png">
This will create a clone of the repository under your own account. Navigate to your profile now and click on the new repository called `monkeytype` under your profile.
### Making a Change
There are two methods to making a change in the code.
#### Option 1 - VS Code Web Editor (Recommended)
If you are not a developer and wish to contribute themes, new languages, or quotes, having a text editor will make contributions _much_ easier. To make complex edits without installing anything, we recommend using GitHub's VS Code web editor. In your fork of Monkeytype (fork it first), go to the `Code` tab of the repo and press <kbd>.</kbd>(the period/dot key). This will open up the repo in an online VS Code instance you can use to edit files in the browser. Once you are done making your changes, go to the Source Control tab in the activity bar with <kbd>Ctrl/Cmd + Shift + G</kbd>, click the `+` next to the files you've changed to stage them, type a brief message summarizing the changes made in the commit, and press <kbd>Ctrl/Cmd + Enter</kbd> to commit your changes to your fork.
Once done, move on to the [next section to create a pull request](#creating-a-pull-request).
#### Option 2 - Github Web UI
You're now ready to make a change. Navigate to the file that you're looking to contribute to in your forked repository. Once you navigate to the file, you should see an `Edit` icon (shaped as a pencil) on the right:
<img width="1552" alt="Screenshot showing how to edit files on the Github Web UI." src="https://user-images.githubusercontent.com/16960551/167073809-4d53f25a-a0f8-4ca3-98d4-8a77f4d8bb8a.png">
Upon clicking this, you'll have the ability to edit the document itself.
_Note however that some files that are too large might not have this option. In these cases you will need to download the code and create edits outside of the Github web UI. Refer to [CONTRIBUTING_ADVANCED.md](./CONTRIBUTING_ADVANCED.md)_
At this point, I would also like to point you to [CONTRIBUTING.md](./CONTRIBUTING.md) to view guidelines for theme, language, and quote contributions.
Once you've completed your change, you're ready to commit them. At the bottom of the edit file screen, you will find the commit UI. In the first box, you want to put in a title that describes the change you made. Then in the description field, you can put in any additional detail to supplement your title further.
You will find two radio buttons, one prompts you to commit directly to your current branch, and the other prompts you to create a new branch for your commit and start a pull request. Select the first option to commit the change directly to your current branch.
Click `Commit changes` once you are ready to proceed.
<img width="1552" alt="Screenshot showing how to commit changes on the Github Web UI." src="https://user-images.githubusercontent.com/16960551/167233463-fb06e4f8-0699-40ea-9ade-f801898cfc93.png">
### Creating a Pull Request
You can repeat the steps above for as many changes as needed. Once you are done making all your code changes and you have commited them to your branch, you are ready to make a pull request (PR). Go back to the main page of your forked repository. Ensure that your current branch (which is likely still master at this point) is up to date. You can do so by clicking the following button:
Update branch:
<img width="1552" alt="Screenshot showing how to update the fork to match the main Monkeytype repository" src="https://user-images.githubusercontent.com/83455454/149186547-5b9fe4fd-b944-4eed-a959-db43f96198bf.png">
Once up to date, you can click the `Contribute` button to open a PR.
Create a pull request:
<img width="1552" alt="Screenshot showing how to create a pull request to the main Monkeytype repository" src="https://user-images.githubusercontent.com/83455454/149186637-66dae488-05ae-45c4-9217-65bc36c4927b.png">
Be sure to add a good description to the PR and that the source and destination branches at the top look correct. The `base repository` and `base branch` should be listed as `monkeytypegame/monkeytype` and `master` respectively, and on the right of that should be your forked repository and the branch you have your changes on.
Once done, click on `Create pull request` to officially publish your PR.
### Merging a Pull Request
All you have to do now is wait for approval or comments and go from there!
Once your PR is approved, all that is left to do is merge it!
## Questions
If you have any questions, comments, concerns, or problems let me know on [GitHub](https://github.com/Miodec), [Discord](https://discord.gg/monkeytype) in the `#development` channel, or ask a question on Monkeytype's [GitHub discussions](https://github.com/monkeytypegame/monkeytype/discussions) and a contributor will be happy to assist you.