gaspersic/freeCodeCamp
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: update intial restructuring for guide articles

Browse Source
This commit is contained in:
Mrugesh Mohapatra
2018-10-10 16:33:06 +05:30
parent 4c4356b8d4
commit 29af7da92b
9 changed files with 685 additions and 506 deletions
Download Patch File Download Diff File Expand all files Collapse all files

397
docs/how-to-setup-freecodecamp-locally.md
View File

@ -1,12 +1,14 @@
# 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.
Follow these guidelines for getting freeCodeCamp 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.
Some of the contribution workflows like previewing pages for the guide or the coding 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.
['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.
@ -20,6 +22,91 @@ Some of the contribution workflows like previewing pages for the guide or the cu
![GIF - How to fork freeCodeCamp on Github](/docs/images/github/how-to-fork-freeCodeCamp.gif)
## 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 your copy of freeCodeCamp
['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
Now that you have a local copy of freeCodeCamp, you can follow these instructions to get it running locally. This will help you to:
- Preview edits to pages as it would appear on the learning platform.
- Work on UI related issues and enhancements.
- Debug and fix issues in the application servers and client apps.
You can skip running freeCodeCamp locally, if you are just editing files, doing a `rebase` or resolving `merge` conflicts. You can always return to this part of the instructions later.
[Skip running freeCodeCamp locally](#making-changes-to-your-clone-of-freecodecamp-locally)
### Installing prerequisites
Start by installing these prerequisite software.
@ -51,79 +138,6 @@ If you are on a different OS, and/or are still running into issues, reach out to
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.
@ -169,17 +183,17 @@ Start the MongoDB server in a separate terminal
- On macOS & Ubuntu:
```shell
mongod
```
```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
Make sure to replace `3.6` with the version you have installed
```shell
"C:\Program Files\MongoDB\Server\3.6\bin\mongod"
```
```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.
@ -212,6 +226,223 @@ Now open a web browser and visit <http://localhost:8000>. If the app loads, cong
Meaning, if you visit <http://localhost:3000/explorer> you should see the APIs that we have.
Congratulations 🎉! You now have a copy of freeCodeCamp's entire learning platform running on your local machine.
## Making changes to your clone of freeCodeCamp locally
Next, you can make changes to files, and commit your changes.
Follow these steps:
1. Check that you are on the `master` branch
```shell
git status
```
You should get a output like this:
```shell
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean
```
If you are not on master or your working directory is not clean, resolve any outstanding files/commits and checkout `master`:
```shell
git checkout master
```
2. Next, you would want to `rebase` from the `upstream`.
This step **will sync the lastest changes** from the main repository of freeCodeCamp. Its important that you rebase as often as possible, to avoid conflicts later.
```shell
git pull --rebase upstream master
```
You can optionally push this branch back to your origin, to have a clean history on your fork on GitHub.
```shell
git push origin master --force
```
3. Next, you will have to create a fresh new branch.
Working on a separate branch for every single issue, helps you keep your local work copy clean. You should never work on the `master`. This will soil your copy of freeCodeCamp and you may have to start over with a fresh clone or fork.
Check that you are on `master` as explained previously, and branch off from there:
```shell
git checkout -b fix/update-guide-for-xyz
```
Your branch name should start with a `fix/`, `feat/`, etc. Avoid, using issue no.s in branches. Keep them short, meaningful and unique.
Some examples of good branch names are:
```md
fix/update-challenges-for-react
fix/update-guide-for-html-css
fix/platform-bug-sign-in-issues
feat/add-guide-article-for-javascript
translate/add-spanish-basic-html
```
And these are really bad name:
```shell
challenges-branch
update-guide
fix/#12345
fix-#123
changes-for-1234
```
4. Next, you can work on the editing pages and working on the code in your favorite text editor.
5. Once you are happy with the changes you should optionally run freeCodeCamp locally to preview the changes.
6. Make sure you fix any errors, and check the formating of your changes. We have style guide for the Guide articles and Coding challenges.
7. Next, check and confirm the files you are updating
```shell
git status
```
This should show a list of `unstaged` files that you have edited.
```shell
On branch feat/documentation
Your branch is up to date with 'upstream/feat/documentation'.
Changes not staged for commit:
(use "git add/rm <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: CONTRIBUTING.md
modified: docs/README.md
modified: docs/how-to-setup-freecodecamp-locally.md
modified: docs/how-to-work-on-guide-articles.md
...
```
8. Stage the changes and make a commit.
In this step you should only mark files that you have edited, or added. You can perform a reset, and resolve files that you did not intend to change.
```shell
git add path/to/my/changed/file.ext
```
Or, alternatively you can add all the `unstaged` files to the staging area:
```shell
git add .
```
Only the files that were moved to the staging area will added when you make a commit.
```shell
git status
```
Output:
```shell
On branch feat/documentation
Your branch is up to date with 'upstream/feat/documentation'.
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
modified: CONTRIBUTING.md
modified: docs/README.md
modified: docs/how-to-setup-freecodecamp-locally.md
modified: docs/how-to-work-on-guide-articles.md
```
Now, you can commit your changes with a short message like so:
```shell
git commit -m "fix: my short commit message"
```
Some examples:
```md
fix: update guide article for Java - for loop
feat: add guide article for alexa skills
```
Optional:
We highly recommend making a conventional commit message. This is a good practice that you will see on some of the popular Open Source repositories. As a developer, this encourages you to follow standard practices.
Some examples of conventional commit messages are:
```md
fix: update HTML guide article
fix: update build scripts for Travis-CI
feat: add article for JavaScript hoisting
docs: update contributing guidelines
```
Keep these short, not more than 50 characters. You can always add additional information in the description of the commit message.
This does not take any additional time than a unconventional message like 'update file' or 'add index.md'
You can learn more at about [why your should these here](https://www.conventionalcommits.org/en/v1.0.0-beta.2/#why-use-conventional-commits).
9. If you realise that you need to edit a file or, update the commit message after making a commit you can do so after editing the files with:
```shell
git commit --amend
```
This will open up a default, text editor like `nano` or `vi` where you can edit the commit message title and add/edit description.
10. Next, you can push your changes to your fork.
```shell
git push origin branch/name-here
```
## Proposing a Pull Request (PR)
1. Once the edits have been committed, you will be prompted to create a pull request on your fork's GitHub Page.
![Image - Compare pull request prompt on GitHub](/docs/images/github/compare-pull-request-prompt.png)
2. By default, all pull requests should be against the freeCodeCamp main repo, `master` branch.
Make sure that your Base Fork is set to freeCodeCamp/freeCodeCamp when raising a Pull Request.**
![Image - Comparing forks when making a pull request](/docs/images/github/comparing-forks-for-pull-request.png)
3. Submit the pull request from your branch to freeCodeCamp's `master` branch.
4. In the body of your PR include a more detailed summary of the changes you made and why.
- You will be presented with a pull request template. This is a checklist that you should have followed before opening the pull request.
- Fill in the details as they seem fit you. This information will be reviewed and decide whether or not, your pull request is going to be accepted.
- If the PR is meant to fix an existing bug/issue then, at the end of
your PR's description, append the keyword `closes` and #xxxx (where xxxx
is the issue number). Example: `closes #1337`. This tells GitHub to
automatically close the existing issue, if the PR is accepted and merged.
5. Indicate if you have tested on a local copy of the site or not.
This is very important when you are making changes that are not copy editing markdown files. For example, changes to CSS or JavaScript code, etc.
## Get your PR accepted
## 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.