2016-02-04 21:59:29 +00:00
|
|
|
|
# Contributor's Guide
|
2015-11-29 09:04:50 +00:00
|
|
|
|
|
2016-04-08 14:40:08 +00:00
|
|
|
|
## Table of Contents
|
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
- [I want to help!](#i-want-to-help)
|
|
|
|
|
- [Contribution Guidelines](#contribution-guidelines)
|
|
|
|
|
- [Prerequisites](#prerequisites)
|
|
|
|
|
- [Getting Started](#getting-started)
|
|
|
|
|
- [Linting Setup](#linting-setup)
|
|
|
|
|
- [Found a bug?](#found-a-bug)
|
|
|
|
|
- [Creating Pull Requests](#creating-pull-requests)
|
|
|
|
|
- [Common Steps](#common-steps)
|
|
|
|
|
- [Next Steps](#next-steps)
|
2016-04-08 14:40:08 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
### I want to help!
|
2015-09-08 16:19:28 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
We welcome pull requests from Free Code Camp campers (our students) and seasoned
|
|
|
|
|
JavaScript developers alike! Follow these steps to contribute:
|
2016-02-04 21:59:29 +00:00
|
|
|
|
|
|
|
|
|
1. Find an issue that needs assistance by searching for the [Help Wanted](https://github.com/FreeCodeCamp/FreeCodeCamp/labels/help%20wanted) tag.
|
2016-07-22 01:44:00 +00:00
|
|
|
|
|
2016-03-24 05:24:52 +00:00
|
|
|
|
2. Let us know you are working on it by posting a comment on the issue.
|
2016-07-22 01:44:00 +00:00
|
|
|
|
|
|
|
|
|
3. Feel free to ask for help in our [Help
|
|
|
|
|
Contributors](https://gitter.im/FreeCodeCamp/HelpContributors) Gitter room.
|
2016-02-04 21:59:29 +00:00
|
|
|
|
|
|
|
|
|
If you've found a bug that is not on the board, [follow these steps](#found-a-bug).
|
2015-11-29 09:04:50 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
### Contribution Guidelines
|
|
|
|
|
|
|
|
|
|
1. Fork the project: [How To Fork And Maintain a Local Instance of Free Code
|
2016-07-30 23:41:25 +00:00
|
|
|
|
Camp](http://forum.freecodecamp.com/t/how-to-fork-and-maintain-a-local-instance-of-free-code-camp/19116)
|
2016-07-22 01:44:00 +00:00
|
|
|
|
|
|
|
|
|
2. Create a branch specific to the issue or feature you are working on. Push
|
|
|
|
|
your work to that branch. ([Need help with
|
|
|
|
|
branching?](https://github.com/Kunena/Kunena-Forum/wiki/Create-a-new-branch-with-git-and-manage-branches))
|
|
|
|
|
|
|
|
|
|
3. Name the branch something like `fix/xxx` or `feature/xxx` where `xxx` is a
|
|
|
|
|
short description of the changes or feature you are attempting to add. For
|
|
|
|
|
example `fix/email-login` would be a branch where I fix something specific
|
|
|
|
|
to email login.
|
2015-11-29 09:04:50 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
4. [Set up Linting](#linting-setup) to run as you make changes.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
5. When you are ready to share your code, run the test suite `npm test` and
|
|
|
|
|
ensure all tests pass. For Windows contributors, skip the jsonlint pretest
|
|
|
|
|
run by using `npm run test-challenges`, as jsonlint will always fail on
|
|
|
|
|
Windows, given the wildcard parameters.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-30 23:41:25 +00:00
|
|
|
|
6. Squash your Commits. Ref: [rebasing](http://forum.freecodecamp.com/t/how-to-use-git-rebase/13226)
|
2016-04-15 07:39:29 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
7. Submit a [pull
|
2016-07-30 23:41:25 +00:00
|
|
|
|
request](http://forum.freecodecamp.com/t/how-to-make-a-pull-request-on-free-code-camp/19114)
|
2016-07-22 01:44:00 +00:00
|
|
|
|
from your branch to Free Code Camp's `staging` branch. [Travis
|
|
|
|
|
CI](https://travis-ci.org/FreeCodeCamp/FreeCodeCamp) will then take your
|
|
|
|
|
code and run `npm test`. Make sure this passes, then we'll do a quick code
|
|
|
|
|
review and give you feedback, then iterate from there.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
### Prerequisites
|
2016-04-08 14:40:08 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
| Prerequisite | Version |
|
|
|
|
|
| ------------------------------------------- | ------- |
|
|
|
|
|
| [MongoDB](http://www.mongodb.org/downloads) | `~ ^3` |
|
|
|
|
|
| [Node.js](http://nodejs.org) | `~ ^4` |
|
|
|
|
|
| npm (comes with Node) | `~ ^2` |
|
|
|
|
|
|
|
|
|
|
> _Updating to the latest releases is recommended_.
|
|
|
|
|
|
|
|
|
|
### Getting Started
|
|
|
|
|
|
|
|
|
|
Note: If this is your first time working with a node-gyp dependent module,
|
|
|
|
|
please follow the [node-gyp installation
|
|
|
|
|
guide](https://github.com/nodejs/node-gyp#installation) to ensure a working npm
|
|
|
|
|
build.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
|
|
|
|
The easiest way to get started is to clone the repository:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# Get the latest snapshot
|
|
|
|
|
git clone --depth=1 https://github.com/freecodecamp/freecodecamp.git freecodecamp
|
|
|
|
|
|
|
|
|
|
# Change directory
|
|
|
|
|
cd freecodecamp
|
|
|
|
|
|
|
|
|
|
# Install NPM dependencies
|
|
|
|
|
npm install
|
|
|
|
|
|
|
|
|
|
# Install Gulp globally
|
|
|
|
|
npm install -g gulp
|
|
|
|
|
|
|
|
|
|
# Install Bower globally
|
|
|
|
|
npm install -g bower
|
|
|
|
|
|
|
|
|
|
# Install Bower dependencies
|
|
|
|
|
bower install
|
|
|
|
|
```
|
2016-07-22 01:44:00 +00:00
|
|
|
|
|
|
|
|
|
_Private Environment Variables (API Keys)_
|
|
|
|
|
|
2016-02-19 19:35:21 +00:00
|
|
|
|
```bash
|
|
|
|
|
# Create a copy of the "sample.env" and name it as ".env".
|
|
|
|
|
# Populate it with the necessary API keys and secrets:
|
|
|
|
|
cp sample.env .env
|
2016-01-02 01:04:47 +00:00
|
|
|
|
```
|
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
Edit your `.env` file and modify the API keys only for services that you will
|
|
|
|
|
use.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
Note : Not all keys are required, to run the app locally, however `MONGOHQ_URL`
|
2016-08-16 12:25:33 +00:00
|
|
|
|
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.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
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.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
|
|
|
|
```bash
|
2016-01-27 23:58:09 +00:00
|
|
|
|
# Start the mongo server in a separate terminal
|
2016-01-02 01:04:47 +00:00
|
|
|
|
mongod
|
|
|
|
|
|
|
|
|
|
# Initialize Free Code Camp
|
|
|
|
|
# This will seed the database for the first time.
|
|
|
|
|
# This command should only be run once.
|
|
|
|
|
npm run only-once
|
|
|
|
|
|
|
|
|
|
# start the application
|
|
|
|
|
gulp
|
|
|
|
|
```
|
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
Now navigate to your browser and open
|
|
|
|
|
<http://localhost:3001>. If the app loads,
|
|
|
|
|
congratulations – you're all set. Otherwise, let us know by opening a GitHub
|
|
|
|
|
issue and with your error.
|
2016-04-08 14:40:08 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
### Linting Setup
|
|
|
|
|
|
|
|
|
|
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 [Free Code Camp's JavaScript Style
|
2016-07-30 23:41:25 +00:00
|
|
|
|
Guide](http://forum.freecodecamp.com/t/free-code-camp-javascript-style-guide/19121)
|
2016-07-22 01:44:00 +00:00
|
|
|
|
(you can find a summary of those rules
|
|
|
|
|
[here](https://github.com/FreeCodeCamp/FreeCodeCamp/blob/staging/.eslintrc).
|
|
|
|
|
Please do not ignore any linting errors, as they are meant to **help** you and
|
|
|
|
|
to ensure a clean and simple code base. Make sure none of your JavaScript is
|
|
|
|
|
longer than 80 characters per line. The reason we enforce this is because one
|
|
|
|
|
of our dependent NPM modules, [jsonlint](https://github.com/zaach/jsonlint),
|
|
|
|
|
does not fully support wildcard paths in Windows.
|
|
|
|
|
|
|
|
|
|
### Found a bug?
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
|
|
|
|
Do not file an issue until you have followed these steps:
|
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
1. Read [Help I've Found a
|
2016-07-30 23:41:25 +00:00
|
|
|
|
Bug](http://forum.freecodecamp.com/t/how-to-report-a-bug/19543)
|
2016-07-22 01:44:00 +00:00
|
|
|
|
wiki page and follow the instructions there.
|
|
|
|
|
|
2016-07-30 23:41:25 +00:00
|
|
|
|
2. Asked for confirmation in the appropriate [Help Room](http://forum.freecodecamp.com/t/free-code-camp-official-chat-rooms/19390/2)
|
2016-07-22 01:44:00 +00:00
|
|
|
|
|
|
|
|
|
3. Please _do not_ open an issue without a 3rd party confirmation of your
|
|
|
|
|
problem.
|
|
|
|
|
|
|
|
|
|
### Creating Pull Requests
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
#### What is a Pull Request?
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
A pull request (PR) is a method of submitting proposed changes to the Free Code
|
|
|
|
|
Camp Repo (or any Repo, for that matter). You will make changes to copies of the
|
|
|
|
|
files which make up Free Code Camp in a personal fork, then apply to have them
|
|
|
|
|
accepted by Free Code Camp proper.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
#### Need Help?
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
Free Code Camp Issue Mods and staff are on hand to assist with Pull Request
|
|
|
|
|
related issues on our Help Contributors Chat Room
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-08-16 12:25:33 +00:00
|
|
|
|
#### How to find the code in the Free Code Camp codebase to fix/edit?
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-08-16 12:25:33 +00:00
|
|
|
|
The best way to find out any code you wish to change/add or remove is using
|
|
|
|
|
the GitHub search bar at the top of the repository page. For example, you could
|
|
|
|
|
search for a challenge name and the results will display all the files along
|
|
|
|
|
with line numbers. Then you can proceed to the files and verify this is the area
|
|
|
|
|
that you were looking forward to edit. Always feel free to reach out to the chat
|
|
|
|
|
room when you are not certain of any thing specific in the code.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
#### Important: ALWAYS EDIT ON A BRANCH
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
Take away only one thing from this document, it should be this: Never, **EVER**
|
|
|
|
|
make edits to the `staging` branch. ALWAYS make a new branch BEFORE you edit
|
|
|
|
|
files. This is critical, because if your PR is not accepted, your copy of
|
|
|
|
|
staging will be forever sullied and the only way to fix it is to delete your
|
|
|
|
|
fork and re-fork.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-08-16 12:25:33 +00:00
|
|
|
|
#### Methods
|
|
|
|
|
|
|
|
|
|
There are two methods of creating a pull request for Free Code Camp:
|
|
|
|
|
|
|
|
|
|
- Editing files via the GitHub Interface
|
|
|
|
|
- Editing files on a local clone
|
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
##### Method 1: Editing via your Local Fork _(Recommended)_
|
|
|
|
|
|
|
|
|
|
This is the recommended method. Read about How to Setup and Maintain a Local
|
|
|
|
|
Instance of Free Code Camp.
|
|
|
|
|
|
|
|
|
|
1. Perform the maintenance step of rebasing `staging`.
|
|
|
|
|
2. Ensure you are on the `staging` branch using `git status`:
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
$ git status
|
|
|
|
|
On branch staging
|
|
|
|
|
Your branch is up-to-date with 'origin/staging'.
|
|
|
|
|
|
|
|
|
|
nothing to commit, working directory clean
|
|
|
|
|
```
|
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
1. If you are not on staging or your working directory is not clean, resolve
|
|
|
|
|
any outstanding files/commits and checkout staging `git checkout staging`
|
|
|
|
|
|
|
|
|
|
2. Create a branch off of `staging` with git: `git checkout -B
|
|
|
|
|
branch/name-here` **Note:** Branch naming is important. Use a name like
|
|
|
|
|
`fix/short-fix-description` or `feature/short-feature-description`. Review
|
|
|
|
|
the [Contribution Guidelines](#contribution-guidelines) for more detail.
|
|
|
|
|
|
|
|
|
|
3. Edit your file(s) locally with the editor of your choice
|
|
|
|
|
|
|
|
|
|
4. Check your `git status` to see unstaged files.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
5. Add your edited files: `git add path/to/filename.ext` You can also do: `git
|
|
|
|
|
add .` to add all unstaged files. Take care, though, because you can
|
|
|
|
|
accidentally add files you don't want added. Review your `git status` first.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
6. Commit your edits: `git commit -m "Brief Description of Commit"`
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
7. Squash your commits, if there are more than one.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
8. Push your commits to your GitHub Fork: `git push -u origin branch/name-here`
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
9. Go to [Common Steps](#common-steps)
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
##### Method 2: Editing via the GitHub Interface
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
Note: Editing via the GitHub Interface is not recommended, since it is not
|
|
|
|
|
possible to update your fork via GitHub's interface without deleting and
|
|
|
|
|
recreating your fork.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
Read the [Wiki
|
2016-07-30 23:41:25 +00:00
|
|
|
|
article](http://forum.freecodecamp.com/t/how-to-make-a-pull-request-on-free-code-camp/19114)
|
2016-07-22 01:44:00 +00:00
|
|
|
|
for further information
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
### Common Steps
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
1. Once the edits have been committed, you will be prompted to create a pull
|
|
|
|
|
request on your fork's GitHub Page.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
2. By default, all pull requests should be against the FCC main repo, `staging`
|
|
|
|
|
branch.
|
2016-01-02 01:04:47 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
3. Submit a [pull
|
2016-07-30 23:41:25 +00:00
|
|
|
|
request](http://forum.freecodecamp.com/t/how-to-contribute-via-a-pull-request/19368)
|
2016-07-22 01:44:00 +00:00
|
|
|
|
from your branch to Free Code Camp's `staging` branch.
|
|
|
|
|
|
|
|
|
|
4. The title (also called the subject) of your PR should be descriptive of your
|
|
|
|
|
changes and succinctly indicates what is being fixed.
|
|
|
|
|
|
|
|
|
|
- **Do not add the issue number in the PR title**.
|
|
|
|
|
|
|
|
|
|
- Examples: `Add Test Cases to Bonfire Drop It` `Correct typo in Waypoint
|
|
|
|
|
Size Your Images`
|
|
|
|
|
|
|
|
|
|
5. In the body of your PR include a more detailed summary of the changes you
|
|
|
|
|
made and why.
|
|
|
|
|
|
|
|
|
|
- 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
|
|
|
|
|
close the existing issue, if the PR is merged.
|
|
|
|
|
|
|
|
|
|
6. Indicate if you have tested on a local copy of the site or not.
|
|
|
|
|
|
|
|
|
|
### Next Steps
|
|
|
|
|
|
|
|
|
|
#### If your PR is accepted
|
|
|
|
|
|
|
|
|
|
Once your PR is accepted, you may delete the branch you created to submit it.
|
|
|
|
|
This keeps your working fork clean.
|
|
|
|
|
|
|
|
|
|
You can do this with a press of a button on the GitHub PR interface. You can
|
|
|
|
|
delete the local copy of the branch with: `git branch -D branch/to-delete-name`
|
|
|
|
|
|
|
|
|
|
#### If your PR is rejected
|
|
|
|
|
|
|
|
|
|
Don't despair! You should receive solid feedback from the Issue Moderators as to
|
|
|
|
|
why it was rejected and what changes are needed.
|
|
|
|
|
|
|
|
|
|
Many Pull Requests, especially first Pull Requests, require correction or
|
|
|
|
|
updating. If you have used the GitHub interface to create your PR, you will need
|
2016-08-17 10:59:39 +00:00
|
|
|
|
to close your PR, create a new branch, and re-submit.
|
2016-07-22 01:44:00 +00:00
|
|
|
|
|
|
|
|
|
If you have a local copy of the repo, you can make the requested changes and
|
|
|
|
|
amend your commit with: `git commit --amend` This will update your existing
|
|
|
|
|
commit. When you push it to your fork you will need to do a force push to
|
|
|
|
|
overwrite your old commit: `git push --force`
|
2015-11-29 09:04:50 +00:00
|
|
|
|
|
2016-01-03 18:20:26 +00:00
|
|
|
|
Be sure to post in the PR conversation that you have made the requested changes.
|
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
### Other resources
|
|
|
|
|
|
|
|
|
|
- [Searching for Your Issue on
|
2016-07-30 23:41:25 +00:00
|
|
|
|
GitHub](http://forum.freecodecamp.com/t/searching-for-existing-issues/19139)
|
2016-07-22 01:44:00 +00:00
|
|
|
|
|
|
|
|
|
- [Creating a New GitHub
|
2016-07-30 23:41:25 +00:00
|
|
|
|
Issue](http://forum.freecodecamp.com/t/creating-a-new-github-issue/18392)
|
2016-07-22 01:44:00 +00:00
|
|
|
|
|
|
|
|
|
- [Select Issues for Contributing Using
|
2016-07-30 23:41:25 +00:00
|
|
|
|
Labels](http://forum.freecodecamp.com/t/free-code-camp-issue-labels/19556)
|
2016-07-22 01:44:00 +00:00
|
|
|
|
|
|
|
|
|
- [How to clone the FreeCodeCamp website on a Windows
|
2016-07-30 23:41:25 +00:00
|
|
|
|
pc](http://forum.freecodecamp.com/t/how-to-clone-and-setup-the-free-code-camp-website-on-a-windows-pc/19366)
|
2016-07-22 01:44:00 +00:00
|
|
|
|
|
|
|
|
|
- [How to log in to your local FCC site - using
|
2016-07-30 23:41:25 +00:00
|
|
|
|
GitHub](http://forum.freecodecamp.com/t/how-to-log-in-to-your-local-instance-of-free-code-camp/19552)
|
2016-07-22 01:44:00 +00:00
|
|
|
|
|
|
|
|
|
- [Writing great git commit
|
2016-07-30 23:41:25 +00:00
|
|
|
|
message](http://forum.freecodecamp.com/t/writing-good-git-commit-messages/13210)
|
2016-04-08 14:40:08 +00:00
|
|
|
|
|
2016-07-22 01:44:00 +00:00
|
|
|
|
- [Contributor Chat Support - For the FCC Repositories, and running a local
|
|
|
|
|
instance](https://gitter.im/FreeCodeCamp/HelpContributors)
|