docs: update contributing guides, and workflows

This commit is contained in:
Mrugesh Mohapatra
2018-10-08 22:26:06 +05:30
parent 3d0523931b
commit 9281aea45f
9 changed files with 330 additions and 37 deletions

View File

@ -10,44 +10,56 @@
</tr>
</table>
# Contributor's Guide
# Contribution Guidelines
Hello 👋 !
freeCodeCamp.org is possible thanks to thousands of kind volunteers like you. We are grateful for your interest in contributing and we are exited to welcome you onboard.
There are a lot of ways you can help and contribute to the community. We are pretty sure, we have something that will interest you. For instance, you can copy edit, and curate content. Write code, report and fix bugs. Triage issues and help moderate and review changes to the codebase. You can help campers, provide feedback and coding assistance and more.
There are a lot of ways you can help and contribute to the community. For instance, you can copy edit, and curate content for guide articles and curriculum. Translate freeCodeCamp into a language that you speak. Write code, report and fix bugs. Triage issues and help moderate and review changes to the codebase. You can help campers, provide feedback and coding assistance and more.
Any and all contributions are welcome alike.
## Here are some fun ways you can help
> **A quick note before getting started:**
>
> We have a ["Code of Conduct"](/docs/CODE_OF_CONDUCT.md) that you should follow at all times. In summary - We want contributing to freeCodeCamp.org, foster a welcoming environment that is safe and inclusive for everyone.
>
> Be polite and succinct in your conversations with fellow contributors. Remember to respect everyone's time and efforts, they are helping the community same as you.
> **Important:**
>
> We have a ["Code of Conduct"](/docs/CODE_OF_CONDUCT) that you should follow at all times.In short - We want contributing to freeCodeCamp.org, foster a welcoming environment that is safe and civil for everyone.
>
> As contributors we should be polite and succinct in our conversations with our fellow volunteers. Let's remember to respect everyone's time and efforts.
Happy Contributing 🎉!
## Here are some fun ways you can help
You can choose to contribute to an area of you interest:
1. [Contribute to this open source codebase. Work on guide articles, curriculum challenges and fix bugs.](#1-contribute-to-this-open-source-codebase)
2. [Help campers on our public forum.](#2-help-campers-on-our-public-forum)
3. [Help us add subtitles on our YouTube channel.](#3-help-us-add-subtitles-on-our-youtube-channel)
1. [Contribute to this open source codebase.](#contribute-to-this-open-source-codebase)
### 1. Contribute to this open source codebase
Help us in creating or editing [guide articles](https://www.freecodecamp.org/guide), [curriculum challenges](https://www.freecodecamp.org/learn) and fixing bugs on the learning platform.
2. Help campers on our [public forum](https://www.freecodecamp.org/forum/).
- ❓ Help campers by [answering their questions](https://www.freecodecamp.org/forum/?max_posts=1).
- 💬 [Give feedback](https://www.freecodecamp.org/forum/c/project-feedback?max_posts=1) on camper projects.
3. Help us add subtitles on our [YouTube channel](https://www.youtube.com/channel/UC8butISFwT-Wl7EV0hUK0BQ/videos).
### Contribute to this open source codebase
We have a huge open source codebase of the thousands of [Curriculum challenges](https://www.freecodecamp.org/learn) and [Guide articles](https://www.freecodecamp.org/guide). These challenges and articles make up the learning content available on the freeCodeCamp.org's learning platform.
You can help us:
- [📖 Research, Write and Update our guide articles.](#%F0%9F%93%96-research-write-and-update-our-guide-articles)
- [💻 Create, Update and Fix Bugs in our curriculum challenges.](#%F0%9F%92%BB-create-update-and-fix-bugs-in-our-curriculum-challenges)
- [📚 Translate guide articles and curriculum challenges.](#%F0%9F%93%9A-translate-guide-articles-and-curriculum-challenges)
- [🛠 Help us fix bugs in freeCodeCamp.org's learning platform.](#%F0%9F%9B%A0-help-us-fix-bugs-in-freecodecamporgs-learning-platform)
- [📝 Research, Write and Update our guide articles.](#research-write-and-update-our-guide-articles)
#### 📖 Research, Write and Update our guide articles
- [💻 Create, Update and Fix Bugs in our curriculum challenges.](#create-update-and-fix-bugs-in-our-curriculum-challenges)
##### What are Guide articles?
- [🌐 Translate guide articles and curriculum challenges.](#translate-guide-articles-and-curriculum-challenges)
- [🛠 Help us fix bugs in freeCodeCamp.org's learning platform.](#help-us-fix-bugs-in-freecodecamporgs-learning-platform)
#### Research, Write and Update our guide articles
**What are Guide articles?**
The Guide articles aim to be short articles to get you started and familiar with these concepts before going on to read more in-depth material.
@ -55,7 +67,7 @@ Guide articles can be an explanation of a syntax, design pattern, what aria labe
You can find an [example article about HTML Elements here](./client/src/pages/html/elements/index.md).
##### What can I write an article about?
**What can I write an article about?**
Front-end development (adjective form with a dash) is when you are working on the front end (noun form with no dash). The same goes with the back end, full stack, and many other compound terms.
@ -65,15 +77,15 @@ To help, find a `stub article` on our [Guide website](https://www.freecodecamp.o
If you can't find a stub about the topic you'd like to write about, you can open a PR that creates the stub and includes your draft article.
**If you would like work on these, follow along these steps:**
If you would like work on these, follow along these guidelines:
### [How to work on Guide articles.](/docs/how-to-work-on-guide-articles.md)
#### Create, Update and Fix Bugs in our curriculum challenges
**[TODO]**
#### 💻 Create, Update and Fix Bugs in our curriculum challenges
**[TODO]**
#### 📚 Translate guide articles and curriculum challenges
#### Translate guide articles and curriculum challenges
You can help us translate our Guide articles and Curriculum challenges for a language that you speak. Currently we have translated versions in:
@ -89,7 +101,7 @@ Most of these versions are machine translated. We would love your help in improv
**[TODO]**
#### 🛠 Help us fix bugs in freeCodeCamp.org's learning platform
#### Help us fix bugs in freeCodeCamp.org's learning platform
Our learning platform runs on a modern JavaScript stack. It has various components, tools and libraries including but not limited to Node.js, MongoDB, LoopBack, OAuth 2.0, React, Gatsby, Webpack, and more.
@ -105,13 +117,6 @@ Contributing to this requires some understanding of APIs, ES6 Syntax and a lot o
**[TODO]**
### 2. Help campers on our [public forum](https://www.freecodecamp.org/forum)
- ❓ Help campers by [answering their questions](https://www.freecodecamp.org/forum/?max_posts=1).
- 💬 [Give feedback](https://www.freecodecamp.org/forum/c/project-feedback?max_posts=1) on camper projects.
### 3. Help us add subtitles on our [YouTube channel](https://www.youtube.com/freeCodeCamp/videos)
## FAQs
**I found a bug that is not on the board. Where and when should I report?**

View File

@ -95,17 +95,17 @@ This code is running live at [freeCodeCamp.org](https://www.freecodecamp.org).
Our community also has:
- a super active [forum](https://forum.freecodecamp.org)
- a super active [forum](https://www.freecodecamp.org/forum)
- thousands of [local study groups](https://study-group-directory.freecodecamp.org/) around the world, where you can code together in person
- Medium's [largest technical publication](https://medium.freecodecamp.org)
- A popular [YouTube channel](https://youtube.com/freecodecamp)
- and a comprehensive [guide to thousands of programming topics](https://guide.freecodecamp.org)
- and a comprehensive [guide to thousands of programming topics](https://www.freecodecamp.org/guide)
### [Join our community here](https://www.freecodecamp.org/signin).
### Found a bug?
If you think you've found a bug, first read the [Help I've Found a Bug](https://forum.freecodecamp.org/t/how-to-report-a-bug/19543) article and follow its instructions. If you're confident it's a new bug, go ahead and create a new GitHub issue. Be sure to include as much information as possible so we can reproduce the bug.
If you think you've found a bug, first read the [Help I've Found a Bug](https://www.freecodecamp.org/forum/t/how-to-report-a-bug/19543) article and follow its instructions. If you're confident it's a new bug, and have confirmed that someone else facing the same issue, go ahead and create a new GitHub issue. Be sure to include as much information as possible so we can reproduce the bug.
### Found a security issue?

48
docs/README.md Normal file
View File

@ -0,0 +1,48 @@
<table>
<tr>
<td> Read these guidelines in </td>
<td><a href="/CONTRIBUTING.md"> English </a></td>
<td><a href="/docs/chinese/README.md"> 中文 </a></td>
<td><a href="/docs/russian/README.md"> русский </a></td>
<td><a href="/docs/arabic/README.md"> عربى </a></td>
<td><a href="/docs/spanish/README.md"> Español </a></td>
<td><a href="/docs/portuguese/README.md"> Português </a></td>
</tr>
</table>
# Documentation
Hello 👋!
This directory contains all of the documentation on contributing to freeCodeCamp.org
## [If you are getting started, start by reading this first.](/CONTRIBUTING.md)
---
## Quick references articles
1. How to work on Guide articles.
2. How to work on Curriculum Challenges.
3. How to setup freeCodeCamp locally.
4. How to catch outgoing emails locally.
## Style guides
1. Style guide for creating guide articles.
2. Style guide for creating curriculum challenges.
## Quick commands reference when working locally
A quick reference to the commands that you will need, when working locally.
| command | description |
| ------- | ----------- |
| `npm run bootstrap` | Bootstraps the different services |
| `npm run seed` | Parse all the challenge markdown files and inserts them into MongoDB. |
| `npm run develop` | Starts the freeCodeCamp API Server and Client Apps |
| `npm test` | Run all JS tests in the system, including client, server, lint and challenge tests |
| `npm run test:client` | Run the client test suite |
| `npm run test:curriculum` | Run the curriculum test suite |
| `npm run test:server` | Run the server test suite |
| `npm run commit` | An interactive tool to help you build a good commit message |

View File

@ -1,4 +1,4 @@
# How to catch outgoing emails for email workflows
# How to catch outgoing emails locally (for email workflows)
> **Note:** This is an **optional** step - Only required when working with email workflows

View File

@ -0,0 +1,240 @@
# Set up freeCodeCamp locally
Follow these guidelines for getting freeCodeCamp running locally on your system. This is highly recommended if you want to be contributing regularly.
Some of the contribution workflows like previewing pages for the guide or the curriculum challenges, debugging and fixing bugs in codebase requires you to have freeCodeCamp running locally.
## Fork the repository on GitHub
['Forking'](https://help.github.com/articles/about-forks/) is a step where you get your own copy of freeCodeCamp's main repository (a.k.a _repo_) on GitHub. This is essential, because this way you are able to work on your copy of freeCodeCamp on GitHub, or download it for working locally. Later, you will be able to request changes to be pulled into the main repository via a pull request.
> **ProTip:**
> The main repository at `https://github.com/freeCodeCamp/freeCodeCamp` is often referred to as `upstream` repository.
> Your fork at `https://github.com/YOUR_USER_NAME/freeCodeCamp` is often referred to as `origin` repository.
**Follow these steps to fork the `https://github.com/freeCodeCamp/freeCodeCamp` repository:**
1. Go to the freeCodeCamp repository on GitHub: <https://github.com/freeCodeCamp/freeCodeCamp>
2. Click the "Fork" Button in the upper right hand corner of the interface ([More Details Here](https://help.github.com/articles/fork-a-repo/))
3. After the repository has been forked, you will be taken to your copy of the freeCodeCamp at `https://github.com/YOUR_USER_NAME/freeCodeCamp`
![GIF - How to fork freeCodeCamp on Github](/docs/images/github/how-to-fork-freeCodeCamp.gif)
### Installing prerequisites
Start by installing these prerequisite software.
| Prerequisite | Version | Notes |
| ------------------------------------------- | ------- | ----- |
| [MongoDB Community Server](https://docs.mongodb.com/manual/administration/install-community/) | `3.6` | [Release Notes](https://docs.mongodb.com/manual/release-notes/), Note: We currently on `3.6`, an [upgrade is planned](https://github.com/freeCodeCamp/freeCodeCamp/issues/18275).
| [Node.js](http://nodejs.org) | `8.x` | [LTS Schedule](https://github.com/nodejs/Release#release-schedule) |
| npm (comes bundled with Node) | `6.x` | Does not have LTS releases, we use the version bundled with Node LTS |
**Important:**
We highly recommend updating to the latest stable releases a.k.a Long Term Support (LTS) versions of the above.
If Node.js or MongoDB is already installed on your machine, run the following commands to validate the versions:
```shell
node -v
mongo --version
npm -v
```
> If you have a different version, please install the recommended version. We can support installation issues for recommended versions only.
**I am having issues with installing the recommended Prerequisites. What should I do?**
We regularly develop on popular and latest operating systems like macOS 10.12 or later, Ubuntu 16.04 or later and Windows 10. Its recommended to lookup your specific issue on resources like: Google, Stack Overflow or Stack Exchange. Chances are that someone has faced the same issue and there is already an answer to your specific query.
If you are on a different OS, and/or are still running into issues, reach out to [contributors community on our public forum](https://www.freeCodeCamp.org/c/contributors) or the [Contributor's Chat room](https://gitter.im/freeCodeCamp/Contributors). We may be able to troubleshoot some common issues.
We can't support you on GitHub, because software installation issues are beyond the scope of this project.
## Preparing the development environment
Once you have the prerequisites installed, you need to prepare you development environment. This is common for many development workflows, and you will need to do this only once.
**Follow these steps to get your development environment ready:**
1. Install [Git](https://git-scm.com/) or your favorite Git client, if you haven't already. Update to the latest version, the one that came bundled with your OS may be outdated.
2. (Optional but recommended) [Setup an SSH Key](https://help.github.com/articles/generating-an-ssh-key/) for GitHub.
3. Install a code editor of your choice.
We highly recommend using [VS Code](https://code.visualstudio.com/) or [Atom](https://atom.io/). These are some great free and open source code editors.
4. Setup linting for your code editor.
You should have [ESLint running in your editor](http://eslint.org/docs/user-guide/integrations.html), and it will highlight anything doesn't conform to [freeCodeCamp's JavaScript Style Guide](http://forum.freecodecamp.org/t/free-code-camp-javascript-style-guide/19121).
> Please do not ignore any linting errors. They are meant to **help** you and to ensure a clean and simple code base.
## Clone the your copy of freeCodeCamp
Now that you have [forked the repository](#fork-the-repository-on-github), [installed the prerequisites](#installing-prerequisites) and [prepared your development environment](#preparing-the-development-environment), next you will need to clone the repository.
['Cloning'](https://help.github.com/articles/cloning-a-repository/) is a step where you **download** a copy of a repository that is either owned by you or someone else from a `remote` location. In your case, this remote location is your `fork` of freeCodeCamp's repository, that should be available at `https://github.com/YOUR_USER_NAME/freeCodeCamp`.
Run these commands on your local machine:
1. Open a Terminal / Command Prompt / Bash Shell in your projects directory
_i.e.: `/yourprojectdirectory/`_
2. Clone your fork of freeCodeCamp, replacing `YOUR_USER_NAME` with your GitHub Username
```shell
git clone https://github.com/YOUR_USER_NAME/freeCodeCamp.git
```
This will download the entire freeCodeCamp repository to your projects directory.
## Setup a `upstream` to the main repository
Now that you have downloaded a copy of your fork, you will need to setup an `upstream`.
As mentioned earlier, the main repository at `https://github.com/freeCodeCamp/freeCodeCamp` is often referred to as `upstream` repository. Your fork at `https://github.com/YOUR_USER_NAME/freeCodeCamp` is often referred to as `origin` repository.
You need to point your local clone to the `upstream` in addition to the `origin`. This is so that you can sync changes from the main repository. This way you do not have to go through forking and cloning again and again.
1. Change directory to the new freeCodeCamp directory:
```shell
cd freeCodeCamp
```
2. Add a remote to the main freeCodeCamp repository:
```shell
git remote add upstream https://github.com/freeCodeCamp/freeCodeCamp.git
```
3. Check the configuration looks good to you:
```shell
git remote -v
```
The output should be something like below:
```shell
origin https://github.com/YOUR_USER_NAME/freeCodeCamp.git (fetch)
origin https://github.com/YOUR_USER_NAME/freeCodeCamp.git (push)
upstream https://github.com/freeCodeCamp/freeCodeCamp.git (fetch)
upstream https://github.com/freeCodeCamp/freeCodeCamp.git (push)
```
## Running freeCodeCamp locally on your machine
Congratulations, you now have a local copy of the freeCodeCamp repository 🎉! Let's jump right into running freeCodeCamp running locally.
### Installing dependencies
Start by installing the dependencies required for the application to startup.
```shell
# Install NPM dependencies
npm install
```
Next lets, bootstrap the various services, i.e. the api-server, the client UI application, etc. You can [learn more about these services in this guide](#).
By bootstrapping you are tying the links between the services. They are semi-independent. Meaning, in production these services are deployed to their own locations, but while running locally you want them all to be available to you.
```shell
# Bootstrap all projects inside this repository
npm run bootstrap
```
Then you need to add the private environment variables (API Keys):
```shell
# Create a copy of the "sample.env" and name it as ".env".
# Populate it with the necessary API keys and secrets:
# macOS / Linux
cp sample.env .env
# Windows
copy sample.env .env
```
The keys are not required to be changed, to run the app locally. You can leave the default values from the `sample.env` as it is.
`MONGOHQ_URL` is the most important one. Unless you have MongoDB running in a setup different than the defaults, the URL in the `sample.env` should work fine.
You can leave the other keys as they are. Keep in mind if you want to use more services you'll have to get your own API keys for those services and edit those entries accordingly in the `.env` file.
### Start MongoDB
You will need to start MongoDB, before you can start the application:
Start the MongoDB server in a separate terminal
- On macOS & Ubuntu:
```shell
mongod
```
- On Windows, you have to instead specify the full path to the `mongod` binary
Make sure to replace `3.6` with the version you have installed
```shell
"C:\Program Files\MongoDB\Server\3.6\bin\mongod"
```
> ProTip:
> You can avoid having to start MongoDB every time, by installing it as a background service.
> You can [learn more about it in their documentation for your OS](https://docs.mongodb.com/manual/administration/install-community/)
### Seeding the database
Next, lets seed the database. In this step, we run the below command that will fill the MongoDB server with some initial data-sets that is required by the other services. This include a few schemas, among other things.
```shell
npm run seed
```
### Start the freeCodeCamp client application and API server
You can now start up the API server and the client applications.
```shell
npm run develop
```
This single command will fire up all the services, including the API server and the client applications available for you to work on.
Now open a web browser and visit <http://localhost:8000>. If the app loads, congratulations you're all set.
> ProTip:
>
> The API Server serves APIs at `http://localhost:3000`
> The Gatsby app serves the client application at `http://localhost:8000`
Meaning, if you visit <http://localhost:3000/explorer> you should see the APIs that we have.
## Getting Help
If you are stuck, and need help, let us know by asking in the ['Contributors' category on our forum](https://www.freecodecamp.org/forum/c/contributors) or the [Contributors chat room](https://gitter.im/FreeCodeCamp/Contributors) on Gitter.
There might be an error in the console of your browser or in Bash / Terminal / Command Line that will help identify the problem.
### Troubleshooting
If the app launches but you are encountering errors with the UI itself, for example if fonts are not being loaded or if the code editor is not displaying properly, you may try the following troubleshooting steps at least once:
```shell
# Remove all installed node modules
rm -rf node_modules ./**/node_modules
# Reinstall npm packages
npm install
# Bootstrap the project
npm run bootstrap
# Seed the database
npm run seed
# Re-start the application
npm run develop
```

View File

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.2 MiB