docs: update intial restructuring for guide articles
This commit is contained in:
Mrugesh Mohapatra
@ -37,15 +37,15 @@ Help us in creating or editing [guide articles](https://www.freecodecamp.org/gui
|
||||
|
||||
### 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.
|
||||
We have a huge open source codebase of the thousands of [Coding 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.](#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)
|
||||
- [💻 Create, Update and Fix Bugs in our coding challenges.](#create-update-and-fix-bugs-in-our-curriculum-challenges)
|
||||
|
||||
- [🌐 Translate guide articles and curriculum challenges.](#translate-guide-articles-and-curriculum-challenges)
|
||||
- [🌐 Translate guide articles and coding 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)
|
||||
|
||||
@ -69,15 +69,15 @@ 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
|
||||
#### Create, Update and Fix Bugs in our coding challenges
|
||||
|
||||
**[TODO]**
|
||||
|
||||
### [How to work on Curriculum Challenges.](/docs/how-to-work-on-curriculum-challenges.md)
|
||||
### [How to work on Coding Challenges.](/docs/how-to-work-on-coding-challenges.md)
|
||||
|
||||
#### Translate guide articles and curriculum challenges
|
||||
#### Translate guide articles and coding challenges
|
||||
|
||||
You can help us translate our Guide articles and Curriculum challenges for a language that you speak. Currently we have translated versions in:
|
||||
You can help us translate our Guide articles and Coding challenges for a language that you speak. Currently we have translated versions in:
|
||||
|
||||
- Chinese (中文)
|
||||
- Russian (русский)
|
||||
|
||||
@ -23,14 +23,14 @@ This directory contains all of the documentation on contributing to freeCodeCamp
|
||||
## Quick references articles
|
||||
|
||||
1. How to work on Guide articles.
|
||||
2. How to work on Curriculum Challenges.
|
||||
2. How to work on Coding 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.
|
||||
2. Style guide for creating coding challenges.
|
||||
|
||||
## Quick commands reference when working locally
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
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.**
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# How to work on curriculum challenges
|
||||
# How to work on coding challenges
|
||||
|
||||
### Changing on GitHub
|
||||
|
||||
@ -2,73 +2,38 @@
|
||||
|
||||
With your help, we can create a comprehensive reference tool that will help millions of people who are learning to code for years to come. 💛
|
||||
|
||||
<!-- TOC -->
|
||||
You can:
|
||||
|
||||
- [How to work on Guide articles](#how-to-work-on-guide-articles)
|
||||
- [Steps](#steps)
|
||||
- [Creating a PR](#creating-a-pr)
|
||||
- [Using GitHub.com](#using-githubcom)
|
||||
- [Cloning Locally](#cloning-locally)
|
||||
- [Running Locally](#running-locally)
|
||||
- [Getting PR Accepted](#getting-pr-accepted)
|
||||
- [Labels](#labels)
|
||||
- [Conflicting/Duplicate Content](#conflictingduplicate-content)
|
||||
- [Requesting Changes](#requesting-changes)
|
||||
- [Travis CI Build](#travis-ci-build)
|
||||
- [Closing](#closing)
|
||||
- [Getting Help](#getting-help)
|
||||
- [Article Style Guide](#article-style-guide)
|
||||
- [Title](#title)
|
||||
- [Modularity](#modularity)
|
||||
- [Code Blocks](#code-blocks)
|
||||
- [Links](#links)
|
||||
- [Images](#images)
|
||||
- [Attributions](#attributions)
|
||||
- [Resources](#resources)
|
||||
- [Formatting](#formatting)
|
||||
- [Technical Writing](#technical-writing)
|
||||
- [Outline](#outline)
|
||||
- [Intro](#intro)
|
||||
- [Content](#content)
|
||||
- [Clarity](#clarity)
|
||||
- [Voice](#voice)
|
||||
- [Passive](#passive)
|
||||
- [Active](#active)
|
||||
- [Point of View](#point-of-view)
|
||||
- [Abbreviations](#abbreviations)
|
||||
- [Proper nouns](#proper-nouns)
|
||||
- [Third-Party Tools](#third-party-tools)
|
||||
- [Reviewing PRs](#reviewing-prs)
|
||||
- [Squash and Merge](#squash-and-merge)
|
||||
- [Filtering PRs](#filtering-prs)
|
||||
- [Templates](#templates)
|
||||
- [Thank you](#thank-you)
|
||||
- [Thank you and congrats](#thank-you-and-congrats)
|
||||
- [Build Error](#build-error)
|
||||
- [Syncing Fork](#syncing-fork)
|
||||
- [Merge Conflicts](#merge-conflicts)
|
||||
- [Duplicate](#duplicate)
|
||||
- [Closing](#closing)
|
||||
- [Help us by Creating and Editing Guide Articles](#steps-for-creating-and-editing-guide-articles).
|
||||
- [Help us reviewing pull requests for Guide Articles]()
|
||||
|
||||
<!-- /TOC -->
|
||||
## Steps for Creating and Editing Guide Articles
|
||||
|
||||
## Steps
|
||||
|
||||
1. 🍴 [Fork this repo](https://github.com/freeCodeCamp/guide#fork-destination-box)
|
||||
1. 🍴 [Fork this repo](https://github.com/freeCodeCamp/freeCodeCamp#fork-destination-box)
|
||||
2. 👀️ Follow the contributing guidelines outlined below.
|
||||
3. 🔧 Make some awesome changes!
|
||||
4. 👉 [Make a pull request](https://github.com/freeCodeCamp/guide/compare)
|
||||
5. 🎉 Get your pull request approved - success!
|
||||
4. 📖 Read this [style guide for best practices](/docs/style-guide-for-guide-articles).
|
||||
5. 👉 [Make a pull request](https://github.com/freeCodeCamp/freeCodeCamp/compare)
|
||||
6. 🎉 Get your pull request approved - success!
|
||||
|
||||
Or just [create an issue](https://github.com/freeCodeCamp/guide/issues) - any little bit of help counts! 😊
|
||||
Or just [create an issue](https://github.com/freeCodeCamp/freeCodeCamp/issues) - any little bit of help counts! 😊
|
||||
|
||||
## Creating a PR
|
||||
### [Follow these recommended guidelines in from our Style guide for a compelling guide article](/docs/style-guide-for-guide-articles.md)
|
||||
|
||||
### Using GitHub.com
|
||||
### Creating a Pull request (PR) to propose changes
|
||||
|
||||
There are two ways you can propose a change to the repository, after you edit or add a Guide article:
|
||||
|
||||
- [Using the GitHub Web Interface on your browser](#using-the-github-web-interface-on-your-browser).
|
||||
- [Working on your local machine](#working-on-your-local-machine) (_recommended_ for previewing changes).
|
||||
|
||||
#### Using the GitHub Web Interface on your browser
|
||||
|
||||
Watch the video demonstration or follow the steps below it:
|
||||
|
||||
|
||||
**[TODO]** Update the GIF recording.
|
||||
|
||||
|
||||
|
||||
1. Go into the **"pages"** folder (located in [`client/src/pages/guide`](/client/src/pages/guide)) and find the article stub you'd like to write or edit.
|
||||
|
||||
@ -80,82 +45,55 @@ Watch the video demonstration or follow the steps below it:
|
||||
|
||||
3. Scroll to the bottom of the screen and add a commit message explaining your changes.
|
||||
|
||||
(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).
|
||||
|
||||
4. Then select the radio button option for **"Create a new branch for this commit and start a pull request"** and click <kbd>Propose file changes</kbd>.
|
||||
|
||||
5. On the next screen, you can add any other details about your PR, then click <kbd>Create pull request</kbd>.
|
||||
|
||||
### Cloning Locally
|
||||
Congratulations 🎉! You have just created a pull request.
|
||||
|
||||
1. Fork this repository
|
||||
#### Working on your local machine (_recommended_ for previewing changes)
|
||||
|
||||
2. Copy it to your local machine by running the following command:
|
||||
You are not required to work on your local machine, unless you would like to preview your edits, or work with UI fixes and enhancements. This is also recommended if you run into git issues like merge conflicts, rebasing, etc.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/YOUR-GITHUB-USERNAME/guide.git
|
||||
```
|
||||
##### Read these guidelines on [How to setup freeCodeCamp locally](/docs/how-to-setup-freecodecamp-locally.md)
|
||||
|
||||
3. Add a remote upstream so git knows where the official freeCodeCamp guide repository is located by running the following command in the local folder where the repository is stored at:
|
||||
|
||||
```bash
|
||||
git remote add upstream https://github.com/freeCodeCamp/guide.git
|
||||
```
|
||||
|
||||
4. Create a new branch for your work with the command `git checkout -b NEW-BRANCH-NAME`.
|
||||
|
||||
> Try to name your branch in a way that describes your article topic, like `fix/article-html`
|
||||
|
||||
5. Write your article, commit your changes locally, and push your new branch to GitHub with the command `git push origin NEW-BRANCH-NAME`
|
||||
|
||||
6. Go to your repository on GitHub and open a PR
|
||||
|
||||
Make sure to maintain your local fork going forward so it stays up-to-date with the freeCodeCamp guide repository.
|
||||
|
||||
The next time you want to contribute, checkout your local `master` branch and run the command `git pull --rebase upstream master` before creating a new branch.
|
||||
|
||||
This will grab all the changes on the official `master` branch without making an additional commit in your local repository.
|
||||
|
||||
### Running Locally
|
||||
|
||||
Make sure to have yarn installed (follow these [instructions](https://yarnpkg.com/en/docs/install) if needed).
|
||||
|
||||
```bash
|
||||
# fork repo
|
||||
|
||||
# clone down your repo
|
||||
git clone https://github.com/YOUR-GITHUB-USERNAME/guide.git
|
||||
|
||||
# navigate to root folder
|
||||
cd guide
|
||||
|
||||
# install dependencies
|
||||
yarn install
|
||||
|
||||
# run locally
|
||||
yarn develop
|
||||
```
|
||||
|
||||
In this project, we are using `yarn` because `netlify` builds our site with `yarn`.
|
||||
|
||||
## Getting PR Accepted
|
||||
### Getting PR Accepted
|
||||
|
||||
Here are a few guidelines the reviewers follow when reviewing PRs:
|
||||
|
||||
- there is a relevant description and title
|
||||
- PR respects the [Article style guide](./CONTRIBUTING.md/#article-style-guide)
|
||||
- PR respects the [style guide](/docs/style-guide-for-guide-articles)
|
||||
- we follow general QA tips found in [Moderator guidelines](https://forum.freecodecamp.org/t/freecodecamp-moderator-guidelines/18295)
|
||||
- as long as a pull request improves or expands the guide, we accept it even if it contains imperfect English or partial content
|
||||
- older pull requests are reviewed first
|
||||
|
||||
### Labels
|
||||
#### Labels
|
||||
|
||||
- **content** is for pull requests that modify the content of articles on the guide (they add a new article or update an existing article)
|
||||
- **duplicate** is for pull requests that have the same content as another open PR
|
||||
- **changes requested** is for pull requests that need a change before getting merged
|
||||
- **stale** is for pull requests with _"changes requested"_ label that doesn't get activity after about 2 weeks and will subsequently be closed.
|
||||
- A _stale_ pull request should be closed.
|
||||
- Here is [an example](https://github.com/freeCodeCamp/guide/pull/235).
|
||||
- Here is [an example](https://github.com/freeCodeCamp/freeCodeCamp/pull/235).
|
||||
|
||||
### Conflicting/Duplicate Content
|
||||
#### Conflicting/Duplicate Content
|
||||
|
||||
A PR is considered a **duplicate** if it makes changes to the same article as another PR.
|
||||
|
||||
@ -169,14 +107,14 @@ It is very likely there will be merge conflicts with duplicate PRs.
|
||||
|
||||
Reviewers will make every effort to resolve these conflicts and merge duplicate PRs.
|
||||
|
||||
### Requesting Changes
|
||||
#### Requesting Changes
|
||||
|
||||
If a pull request is not perfect, the reviewer may:
|
||||
|
||||
- request changes to the contributor and add the *changes requested* label
|
||||
- fix minor issues and make a commit on top of the PR
|
||||
|
||||
### Travis CI Build
|
||||
#### Travis CI Build
|
||||
|
||||
All PRs must pass the Travis CI checks before we can merge it.
|
||||
|
||||
@ -192,16 +130,16 @@ You will need to fix the issue before we can merge your PR:
|
||||
2. Your PR creates a new folder and the folder name isn't formatted correctly.
|
||||
- Your folder name should be all lowercase and formated in kebab-case (i.e. my-new-folder).
|
||||
3. The article doesn't have a `title` field at the top.
|
||||
- Please refer to [Title](#title) section below under [Article Style Guide](#article-style-guide).
|
||||
- Please refer to [Title](#title) section below under [Style guide for writing articles](/docs/style-guide-for-guide-articles.md).
|
||||
|
||||
### Closing
|
||||
### When do we close pull requests
|
||||
|
||||
We close a pull request
|
||||
|
||||
- if an older PR for the same article is merged, and your PR doesn't add new content
|
||||
- if there is zero/little effort in it (e.g: copy pasting from another source like Wikipedia)
|
||||
- if there is copied text from a copyrighted source - see [Citation issue](https://github.com/freeCodeCamp/guide/issues/2503)
|
||||
- if it does not respect the [Article Style Guide](#article-style-guide)
|
||||
- if there is copied text from a copyrighted source - see [Citation issue](https://github.com/freeCodeCamp/freeCodeCamp/issues/2503)
|
||||
- if it does not respect the [Style guide for writing articles](/docs/style-guide-for-guide-articles.md)
|
||||
- if it does not respect the [Academic Honesty policy](https://www.freecodecamp.org/academic-honesty)
|
||||
- if it is stale (if a change is requested and there is no activity for about 2 weeks)
|
||||
|
||||
@ -221,290 +159,9 @@ There's a community of support from a whole team of contributors, whom you can b
|
||||
|
||||
Stay active in the [contributors chat room](https://gitter.im/freecodecamp/contributors) and ask lots of questions.
|
||||
|
||||
## Article Style Guide
|
||||
|
||||
We've written the following guide to writing Guide articles to help you get started contributing.
|
||||
|
||||
### Title
|
||||
|
||||
Article titles should be as short, concise, and to-the-point as possible.
|
||||
|
||||
We want campers to quickly find the information they're looking for, and the title should reflect the main theme of the article.
|
||||
|
||||
Folder name is used in the URL, so only use dashes -, numbers 0-9, and lowercase letters a-z for it.
|
||||
|
||||
However, you can include special characters in the article title.
|
||||
|
||||
Here are some examples of properly named titles:
|
||||
|
||||
> [`src/pages/html/tables/index.md`](https://github.com/freeCodeCamp/guide/blob/master/src/pages/html/tables/index.md)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Tables
|
||||
---
|
||||
```
|
||||
|
||||
> [`src/pages/css/borders/index.md`](https://github.com/freeCodeCamp/guide/blob/master/src/pages/css/borders/index.md)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Borders
|
||||
---
|
||||
```
|
||||
|
||||
> [`src/pages/javascript/loops/for-loop/index.md`](https://github.com/freeCodeCamp/guide/blob/master/src/pages/javascript/loops/for-loop/index.md)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: For Loop
|
||||
---
|
||||
```
|
||||
|
||||
### Modularity
|
||||
|
||||
Each article should explain exactly one concept, and that concept should be apparent from the article's title.
|
||||
|
||||
We can reference other articles by linking to them inline, or in an "Other Resources" section at the end of the article.
|
||||
|
||||
Our goal is to have thousands of articles that cover a broad range of technical topics.
|
||||
|
||||
### Code Blocks
|
||||
|
||||
Campers will likely use Guide articles as a quick reference to look up syntax. Articles should have simple real-world examples that show common-use cases of that syntax.
|
||||
|
||||
GitHub-flavored markdown supports [syntax highlighting in code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting) for many programming languages.
|
||||
|
||||
To use it, indicate the language after ```.
|
||||
|
||||
For example, the following Markdown
|
||||
|
||||
```markdown
|
||||
```html
|
||||
<div class='awesome' id='more-awesome'>
|
||||
<p>This is text in html</p>
|
||||
</div>
|
||||
```
|
||||
```
|
||||
|
||||
will output the following code block with `HTML` syntax highlighting since we indicated the language `html` after the ```.
|
||||
|
||||
```html
|
||||
<div class='awesome' id='more-awesome'>
|
||||
<p>This is text in html</p>
|
||||
</div>
|
||||
```
|
||||
|
||||
The following represents two other examples using JavaScript and CSS syntax highlighting.
|
||||
|
||||
```markdown
|
||||
```javascript
|
||||
function logTheThings(stuff) {
|
||||
console.log(stuff);
|
||||
}
|
||||
```
|
||||
|
||||
```css
|
||||
.awesome {
|
||||
background-color: #FCCFCC;
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
Please keep the following recommendations in mind:
|
||||
|
||||
- To ensure correct rendering, each codeblock must have a language label. You can find a list of supported languages [here](http://prismjs.com/#languages-list ).
|
||||
- For codeblocks with no appropriate language, use generic labels like ` ```text `, or ` ```code `.
|
||||
- You may know about markdown's four-space indentation syntax for writing codeblocks. However, this is currently __not__ supported by our rendering system.
|
||||
|
||||
Finally, here are some suggested formatting guidelines when writing code blocks:
|
||||
|
||||
- JavaScript statements should end with a `;` semicolon
|
||||
- Comments made should have a space between the comment characters and the comment themselves
|
||||
```javascript
|
||||
// Like this
|
||||
```
|
||||
|
||||
### Links
|
||||
|
||||
Use Markdown style links in your articles to link to other websites.
|
||||
|
||||
```markdown
|
||||
[freeCodeCamp](https://www.freecodecamp.org/)
|
||||
```
|
||||
|
||||
### Images
|
||||
|
||||
For including images, if they aren't already hosted somewhere else on the web, you will need to put them online yourself using a platform like [Imgur](https://imgur.com/) or [Flickr](https://www.flickr.com). You can also host images by committing them to a git repository and pushing it to GitHub. Then you can right-click the image and copy its URL.
|
||||
|
||||
We don't allow hosting images directly in the git repository because it would make it far too big (people pulling it to their local system to make changes would end up downloading all the images), and because it is easier to change an image by just changing the URL in an article than by putting the new image in the repository.
|
||||
|
||||
To include the image in your article, use the appropriate markdown syntax:
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
Then the images should show up when you click the <kcd>Preview</kcd> tab.
|
||||
|
||||
You can also add diagrams, graphics, or visualizations as necessary.
|
||||
|
||||
You can even embed relevant YouTube videos and interactive [REPL.it](https://repl.it/) code editors.
|
||||
|
||||
Don't use emojis or emoticons in the Guide. freeCodeCamp has a global community, and the cultural meaning of an emoji or emoticon may be different around the world. Also, emojis can render differently on different systems.
|
||||
|
||||
### Attributions
|
||||
|
||||
To minimize the potential for plagiarism and maintain integrity in this guide, it is important to give credit where necessary.
|
||||
|
||||
Any material quoted, or used directly and unchanged, from source material should be wrapped in quotation marks and be adequately cited. Material that is not a direct quote but is still paraphrased from a different resource should also be cited.
|
||||
|
||||
You can create superscript numerals to mark content that is cited using `<sup></sup>` tags.
|
||||
|
||||
Like so: <sup>1</sup>
|
||||
|
||||
1. freeCodeCamp - Attributions
|
||||
|
||||
Then, at the bottom of your article, place a
|
||||
|
||||
```markdown
|
||||
### Sources
|
||||
```
|
||||
|
||||
heading and include all of your citations numbered to correspond with your sources.
|
||||
|
||||
An example is highlighted below.
|
||||
|
||||
```markdown
|
||||
Here is some content that should be cited.<sup>1</sup>
|
||||
|
||||
And here is even more that should be cited from another source.<sup>2</sup>
|
||||
|
||||
### Sources
|
||||
|
||||
1. [Doe, John. "Authoring Words." *WikiCoder*. January 1, 1970. Accessed: October 20, 2017](#)
|
||||
2. [Purdue OWL Staff. "MLA Works Cited: Electronic Sources." *Purdue Online Writing Lab.* October 12, 2017. Accessed: October 20, 2017.](https://owl.english.purdue.edu/owl/resource/747/08/)
|
||||
```
|
||||
|
||||
You can check out the Purdue link above to see how to properly cite web sources (they even show how to cite tweets!).
|
||||
|
||||
Typically, an attribution has a structure like the following:
|
||||
|
||||
> Author Last Name, Author First Name. "Article Title." *Publication.* Publisher. Date Published. Date Accessed.
|
||||
|
||||
If you cannot find an author or published date, which is common, simply omit these.
|
||||
|
||||
Use of proper citations will not only keep the guide reputable, but these citations and links will also provide valuable resources should the reader want to learn more about the topic.
|
||||
|
||||
Also note that instances of blatant plagiarism will be either removed or have their pull requests declined, and the user will receive a warning.
|
||||
|
||||
Please refer to and review freeCodeCamp's [Academic Honesty Policy](https://www.freecodecamp.org/academic-honesty) before contributing.
|
||||
|
||||
### Resources
|
||||
|
||||
If there are other Guide resources you think campers would benefit from, add them at the bottom in a "Resources" section with a bulleted list.
|
||||
|
||||
```markdown
|
||||
### Resources
|
||||
|
||||
- [A New Resource](#link)
|
||||
```
|
||||
|
||||
### Formatting
|
||||
|
||||
Use double quotes where applicable.
|
||||
|
||||
Format language keywords as code - this is done with the backtick key (located to the left of the "1" key on a US keyboard) in GitHub-flavored markdown. For example, put back ticks around HTML tag names or CSS property names.
|
||||
|
||||
Use the Oxford Comma when possible (it is a comma used after the penultimate item in a list of three or more items, before ‘and’ or ‘or’ e.g. an Italian painter, sculptor, and architect). It makes things easier, clearer, and prettier to read.
|
||||
|
||||
## Technical Writing
|
||||
|
||||
Technical writing, or the literature of science and technology, is hard.
|
||||
|
||||
You'll need to take a technical (usually abstract) topic and explain it in a clear, accurate, and objective manner.
|
||||
|
||||
You'll likely go through several rounds of proofreading and editing before you're happy with the result.
|
||||
|
||||
### Outline
|
||||
|
||||
Before you begin writing, create an outline of the topic and think about any coding examples you'll use (if applicable).
|
||||
|
||||
This helps to organize your thoughts and make the writing process easier.
|
||||
|
||||
### Intro
|
||||
|
||||
The introduction paragraph should only be 1-2 sentences long and be a simple explanation of the main topic. It should limit the use of any links to other Guide articles, as they can be distracting.
|
||||
|
||||
### Content
|
||||
|
||||
Keep paragraphs short (around 1-4 sentences). People are more likely to read several short paragraphs over a wall of text.
|
||||
|
||||
### Clarity
|
||||
|
||||
Articles should be written with short, clear sentences, and use as little jargon as necessary.
|
||||
|
||||
All jargon should be defined immediately in plain English.
|
||||
|
||||
### Voice
|
||||
|
||||
Use active voice instead of passive voice. Generally, it's a stronger and more straightforward way to communicate a subject. For example:
|
||||
|
||||
#### Passive
|
||||
|
||||
The `for` loop in JavaScript is used by programmers to...
|
||||
|
||||
#### Active
|
||||
|
||||
Programmers use the `for` loop in JavaScript to...
|
||||
|
||||
### Point of View
|
||||
|
||||
Text should use the second person ("you") to help to give it a conversational tone.
|
||||
|
||||
This way, the text and instructions seem to speak directly to the camper reading it.
|
||||
|
||||
Try to avoid using the first person ("I", "we", "let's", and "us").
|
||||
|
||||
### Abbreviations
|
||||
|
||||
If you want to abbreviate a term in your article, write it out fully first, then put the abbreviation in parentheses.
|
||||
|
||||
For example, `"In computer science, an abstract syntax tree (AST) is ..."`
|
||||
|
||||
### Proper nouns
|
||||
|
||||
Proper nouns should use correct capitalization when possible. Below is a list of words as they should appear in Guide articles.
|
||||
|
||||
- JavaScript (capital letters in "J" and "S" and no abbreviations)
|
||||
- Node.js
|
||||
|
||||
Front-end development (adjective form with a dash) is when you working on the front end (noun form with no dash). The same goes with the back end, full stack, and many other compound terms.
|
||||
|
||||
### Third-Party Tools
|
||||
|
||||
To check for grammar and spelling, we recommend using an app like [Grammarly](https://grammarly.com) or a built in extension/plugin that checks for this within your text editor.
|
||||
|
||||
- [VS Code](https://code.visualstudio.com/) - [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)
|
||||
- [Sublime Text 3](https://www.sublimetext.com/docs/3/spell_checking.html)
|
||||
|
||||
To check your writing style, we recommend the [Hemingway App](http://www.hemingwayapp.com/).
|
||||
|
||||
There’s nothing magical about this simple tool, but it will automatically detect widely agreed-upon style issues:
|
||||
|
||||
- passive voice
|
||||
- unnecessary adverbs
|
||||
- words that have more common equivalents
|
||||
|
||||
The Hemingway App will assign a "grade level" for your writing.
|
||||
|
||||
You should aim for a grade level of 6.
|
||||
|
||||
Another tool available is the [De-Jargonizer](http://scienceandpublic.com/), originally designed for scientific communication but might help avoid overspecialized wording.
|
||||
|
||||
---
|
||||
|
||||
# Reviewing PRs
|
||||
## Steps for revewing pull requests for Guide Articles
|
||||
|
||||
> This section is targeted at reviewers of this repo.
|
||||
|
||||
@ -514,28 +171,28 @@ We use the <kcd>Squash and merge</kcd> option when merging the PR which keeps th
|
||||
|
||||
|
||||
|
||||
## Filtering PRs
|
||||
### Filtering PRs
|
||||
|
||||
> PR, Open, Oldest First, Travis CI Build successful, no one assigned, no comments
|
||||
|
||||
[`is:pr is:open sort:updated-asc status:success no:assignee comments:0`](https://github.com/freeCodeCamp/guide/pulls?utf8=%E2%9C%93&q=is%3Apr%20is%3Aopen%20sort%3Aupdated-asc%20status%3Asuccess%20no%3Aassignee%20comments%3A0)
|
||||
[`is:pr is:open sort:updated-asc status:success no:assignee comments:0`](https://github.com/freeCodeCamp/freeCodeCamp/pulls?utf8=%E2%9C%93&q=is%3Apr%20is%3Aopen%20sort%3Aupdated-asc%20status%3Asuccess%20no%3Aassignee%20comments%3A0)
|
||||
|
||||
> PR, Open, Oldest First, Does not have labels: `platform`, `enhancement`, `invalid` or `changes requested`
|
||||
|
||||
[`is:pr is:open sort:updated-asc -label:platform -label:enhancement -label:invalid -label:"changes requested"`](https://github.com/freeCodeCamp/guide/pulls?utf8=%E2%9C%93&q=is%3Apr%20is%3Aopen%20sort%3Aupdated-asc%20-label%3Aplatform%20-label%3Aenhancement%20-label%3Ainvalid%20-label%3A%22changes%20requested%22).
|
||||
[`is:pr is:open sort:updated-asc -label:platform -label:enhancement -label:invalid -label:"changes requested"`](https://github.com/freeCodeCamp/freeCodeCamp/pulls?utf8=%E2%9C%93&q=is%3Apr%20is%3Aopen%20sort%3Aupdated-asc%20-label%3Aplatform%20-label%3Aenhancement%20-label%3Ainvalid%20-label%3A%22changes%20requested%22).
|
||||
|
||||
## Templates
|
||||
### Templates
|
||||
|
||||
> You can make your own with GitHub's built in [**Saved replies**](https://github.com/settings/replies/) feature or use the ones below.
|
||||
|
||||
### Thank you
|
||||
#### Thank you
|
||||
|
||||
```markdown
|
||||
Thank you for your contribution to the page! 👍
|
||||
We're happy to accept these changes, and look forward to future contributions. 🎉
|
||||
```
|
||||
|
||||
### Thank you and congrats
|
||||
#### Thank you and congrats
|
||||
|
||||
> For thanking and encouraging first-time contributors.
|
||||
|
||||
@ -546,7 +203,7 @@ Thank you for your contribution to the page! 👍
|
||||
We're happy to accept these changes, and look forward to future contributions. 📝
|
||||
```
|
||||
|
||||
### Build Error
|
||||
#### Build Error
|
||||
|
||||
```markdown
|
||||
Hey @username
|
||||
@ -557,12 +214,12 @@ Once you resolve these issues, I will be able to review your PR and merge it.
|
||||
|
||||
---
|
||||
|
||||
> Feel free to reference the [Article Style Guide](https://github.com/freeCodeCamp/guide#article-title) for this repo on formatting an article correctly so your Travis CI build passes. ✅
|
||||
> Feel free to reference the [Style guide for writing articles](https://github.com/freeCodeCamp/freeCodeCamp#article-title) for this repo on formatting an article correctly so your Travis CI build passes. ✅
|
||||
>
|
||||
> Also, it's good practice on GitHub to write a brief description of your changes when creating a PR. 📝
|
||||
```
|
||||
|
||||
### Syncing Fork
|
||||
#### Syncing Fork
|
||||
|
||||
> When PR is not up to date with `master` branch.
|
||||
|
||||
@ -577,19 +234,19 @@ Error: ENOTDIR: not a directory, open 'src/pages/java/data-abstraction/index.md'
|
||||
|
||||
This particular error was not actually caused by your file but was an old error caused by merging faulty code to the `master` branch. It has since been resolved.
|
||||
|
||||
To pass the build, you will have to sync the latest changes from the `master` branch of the `freeCodeCamp/guide` repo.
|
||||
To pass the build, you will have to sync the latest changes from the `master` branch of the `freeCodeCamp/freeCodeCamp` repo.
|
||||
|
||||
Using the command line, you can do this in three easy steps:
|
||||
|
||||
```bash
|
||||
git remote add upstream git://github.com/freeCodeCamp/guide.git
|
||||
git remote add upstream git://github.com/freeCodeCamp/freeCodeCamp.git
|
||||
|
||||
git fetch upstream
|
||||
|
||||
git pull upstream master
|
||||
```
|
||||
|
||||
If you're using a GUI, you can simply `Add a new remote...` and use the link `git://github.com/freeCodeCamp/guide.git` from above.
|
||||
If you're using a GUI, you can simply `Add a new remote...` and use the link `git://github.com/freeCodeCamp/freeCodeCamp.git` from above.
|
||||
|
||||
Once you sync your fork and pass the build, I will be able to review your PR and merge it. 😊
|
||||
|
||||
@ -600,7 +257,7 @@ Once you sync your fork and pass the build, I will be able to review your PR and
|
||||
> Also, it's good practice on GitHub to write a brief description of your changes when creating a PR. 📝
|
||||
``````
|
||||
|
||||
### Merge Conflicts
|
||||
#### Merge Conflicts
|
||||
|
||||
> When PR has merge conflicts that need to be resolved.¹
|
||||
|
||||
@ -619,7 +276,7 @@ Once you resolve these conflicts, I will be able to review your PR and merge it.
|
||||
```
|
||||
¹ If a first-time-contributor has a merge conflict maintainers will resolve the conflict for them.
|
||||
|
||||
### Duplicate
|
||||
#### Duplicate
|
||||
|
||||
> When PR is repetitive or a duplicate.
|
||||
|
||||
@ -637,14 +294,14 @@ Thanks again! 😊
|
||||
> If you have any questions, feel free to reach out through [Gitter](https://gitter.im/FreeCodeCamp/Contributors) or by commenting below. 💬
|
||||
```
|
||||
|
||||
### Closing
|
||||
#### Closing invalid pull requests
|
||||
|
||||
> When PR is invalid.
|
||||
|
||||
```markdown
|
||||
Hey @username
|
||||
|
||||
You haven't actually added any content so I will be closing this PR and marking it as `invalid`. 😓️
|
||||
You haven't actually added any content so I will be invalid pull requests this PR and marking it as `invalid`. 😓️
|
||||
|
||||
Feel free to open another PR though! 👍
|
||||
```
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 26 KiB |
BIN
docs/images/github/compare-pull-request-prompt.png
Normal file
BIN
docs/images/github/compare-pull-request-prompt.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 90 KiB |
BIN
docs/images/github/comparing-forks-for-pull-request.png
Normal file
BIN
docs/images/github/comparing-forks-for-pull-request.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 178 KiB |
291
docs/style-guide-for-guide-articles.md
Normal file
291
docs/style-guide-for-guide-articles.md
Normal file
@ -0,0 +1,291 @@
|
||||
# Style guide for creating and editing Guide Articles
|
||||
|
||||
We recommend the following guidelines to writing Guide articles to help you get started contributing and create helpful articles.
|
||||
|
||||
## Title
|
||||
|
||||
Article titles should be as short, concise, and to-the-point as possible.
|
||||
|
||||
We want campers to quickly find the information they're looking for, and the title should reflect the main theme of the article.
|
||||
|
||||
Folder name is used in the URL, so only use dashes -, numbers 0-9, and lowercase letters a-z for it.
|
||||
|
||||
However, you can include special characters in the article title.
|
||||
|
||||
Here are some examples of properly named titles:
|
||||
|
||||
> [`src/pages/html/tables/index.md`](https://github.com/freeCodeCamp/freeCodeCamp/blob/master/src/pages/html/tables/index.md)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Tables
|
||||
---
|
||||
```
|
||||
|
||||
> [`src/pages/css/borders/index.md`](https://github.com/freeCodeCamp/freeCodeCamp/blob/master/src/pages/css/borders/index.md)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Borders
|
||||
---
|
||||
```
|
||||
|
||||
> [`src/pages/javascript/loops/for-loop/index.md`](https://github.com/freeCodeCamp/freeCodeCamp/blob/master/src/pages/javascript/loops/for-loop/index.md)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: For Loop
|
||||
---
|
||||
```
|
||||
|
||||
## Modularity
|
||||
|
||||
Each article should explain exactly one concept, and that concept should be apparent from the article's title.
|
||||
|
||||
We can reference other articles by linking to them inline, or in an "Other Resources" section at the end of the article.
|
||||
|
||||
Our goal is to have thousands of articles that cover a broad range of technical topics.
|
||||
|
||||
## Code Blocks
|
||||
|
||||
Campers will likely use Guide articles as a quick reference to look up syntax. Articles should have simple real-world examples that show common-use cases of that syntax.
|
||||
|
||||
GitHub-flavored markdown supports [syntax highlighting in code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting) for many programming languages.
|
||||
|
||||
To use it, indicate the language after ```.
|
||||
|
||||
For example, the following Markdown
|
||||
|
||||
```markdown
|
||||
```html
|
||||
<div class='awesome' id='more-awesome'>
|
||||
<p>This is text in html</p>
|
||||
</div>
|
||||
```
|
||||
```
|
||||
|
||||
will output the following code block with `HTML` syntax highlighting since we indicated the language `html` after the ```.
|
||||
|
||||
```html
|
||||
<div class='awesome' id='more-awesome'>
|
||||
<p>This is text in html</p>
|
||||
</div>
|
||||
```
|
||||
|
||||
The following represents two other examples using JavaScript and CSS syntax highlighting.
|
||||
|
||||
```markdown
|
||||
```javascript
|
||||
function logTheThings(stuff) {
|
||||
console.log(stuff);
|
||||
}
|
||||
```
|
||||
|
||||
```css
|
||||
.awesome {
|
||||
background-color: #FCCFCC;
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
Please keep the following recommendations in mind:
|
||||
|
||||
- To ensure correct rendering, each codeblock must have a language label. You can find a list of supported languages [here](http://prismjs.com/#languages-list ).
|
||||
- For codeblocks with no appropriate language, use generic labels like ` ```text `, or ` ```code `.
|
||||
- You may know about markdown's four-space indentation syntax for writing codeblocks. However, this is currently __not__ supported by our rendering system.
|
||||
|
||||
Finally, here are some suggested formatting guidelines when writing code blocks:
|
||||
|
||||
- JavaScript statements should end with a `;` semicolon
|
||||
- Comments made should have a space between the comment characters and the comment themselves
|
||||
```javascript
|
||||
// Like this
|
||||
```
|
||||
|
||||
## Links
|
||||
|
||||
Use Markdown style links in your articles to link to other websites.
|
||||
|
||||
```markdown
|
||||
[freeCodeCamp](https://www.freecodecamp.org/)
|
||||
```
|
||||
|
||||
> **Important**
|
||||
> Make sure that you are using HTTPS links. This is very important to avoid insecure content warnings.
|
||||
>
|
||||
> Also, do not use short links like `bit.ly` or `amzn.to` links. This is a security risk. Short links are [vulnerable to redirection based attacks](https://security.stackexchange.com/questions/59517/are-url-shorteners-vulnerable-due-to-open-redirects).
|
||||
>
|
||||
> Instead, simply use the long version of the links, removing any query parameters.
|
||||
> Ex:
|
||||
> `https://example.com/a-long/url/to-a-webpage/?queryParam=something&queryParam=somethingelse`
|
||||
> becomes
|
||||
> `https://example.com/a-long/url/to-a-webpage/`
|
||||
|
||||
## Images
|
||||
|
||||
For including images, if they aren't already hosted somewhere else on the web, you will need to put them online yourself using a platform like [Imgur](https://imgur.com/) or [Flickr](https://www.flickr.com). You can also host images by committing them to a git repository and pushing it to GitHub. Then you can right-click the image and copy its URL.
|
||||
|
||||
We don't allow hosting images directly in the git repository because it would make it far too big (people pulling it to their local system to make changes would end up downloading all the images), and because it is easier to change an image by just changing the URL in an article than by putting the new image in the repository.
|
||||
|
||||
To include the image in your article, use the appropriate markdown syntax:
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
Then the images should show up when you click the <kcd>Preview</kcd> tab.
|
||||
|
||||
You can also add diagrams, graphics, or visualizations as necessary.
|
||||
|
||||
You can even embed relevant YouTube videos and interactive [REPL.it](https://repl.it/) code editors.
|
||||
|
||||
Don't use emojis or emoticons in the Guide. freeCodeCamp has a global community, and the cultural meaning of an emoji or emoticon may be different around the world. Also, emojis can render differently on different systems.
|
||||
|
||||
## Attributions
|
||||
|
||||
To minimize the potential for plagiarism and maintain integrity in this guide, it is important to give credit where necessary.
|
||||
|
||||
Any material quoted, or used directly and unchanged, from source material should be wrapped in quotation marks and be adequately cited. Material that is not a direct quote but is still paraphrased from a different resource should also be cited.
|
||||
|
||||
You can create superscript numerals to mark content that is cited using `<sup></sup>` tags.
|
||||
|
||||
Like so: <sup>1</sup>
|
||||
|
||||
1. freeCodeCamp - Attributions
|
||||
|
||||
Then, at the bottom of your article, place a
|
||||
|
||||
```markdown
|
||||
### Sources
|
||||
```
|
||||
|
||||
heading and include all of your citations numbered to correspond with your sources.
|
||||
|
||||
An example is highlighted below.
|
||||
|
||||
```markdown
|
||||
Here is some content that should be cited.<sup>1</sup>
|
||||
|
||||
And here is even more that should be cited from another source.<sup>2</sup>
|
||||
|
||||
### Sources
|
||||
|
||||
1. [Doe, John. "Authoring Words." *WikiCoder*. January 1, 1970. Accessed: October 20, 2017](#)
|
||||
2. [Purdue OWL Staff. "MLA Works Cited: Electronic Sources." *Purdue Online Writing Lab.* October 12, 2017. Accessed: October 20, 2017.](https://owl.english.purdue.edu/owl/resource/747/08/)
|
||||
```
|
||||
|
||||
You can check out the Purdue link above to see how to properly cite web sources (they even show how to cite tweets!).
|
||||
|
||||
Typically, an attribution has a structure like the following:
|
||||
|
||||
> Author Last Name, Author First Name. "Article Title." *Publication.* Publisher. Date Published. Date Accessed.
|
||||
|
||||
If you cannot find an author or published date, which is common, simply omit these.
|
||||
|
||||
Use of proper citations will not only keep the guide reputable, but these citations and links will also provide valuable resources should the reader want to learn more about the topic.
|
||||
|
||||
Also note that instances of blatant plagiarism will be either removed or have their pull requests declined, and the user will receive a warning.
|
||||
|
||||
Please refer to and review freeCodeCamp's [Academic Honesty Policy](https://www.freecodecamp.org/academic-honesty) before contributing.
|
||||
|
||||
## Resources
|
||||
|
||||
If there are other Guide resources you think campers would benefit from, add them at the bottom in a "Resources" section with a bulleted list.
|
||||
|
||||
```markdown
|
||||
### Resources
|
||||
|
||||
- [A New Resource](#link)
|
||||
```
|
||||
|
||||
## Formatting
|
||||
|
||||
Use double quotes where applicable.
|
||||
|
||||
Format language keywords as code - this is done with the backtick key (located to the left of the "1" key on a US keyboard) in GitHub-flavored markdown. For example, put back ticks around HTML tag names or CSS property names.
|
||||
|
||||
Use the Oxford Comma when possible (it is a comma used after the penultimate item in a list of three or more items, before ‘and’ or ‘or’ e.g. an Italian painter, sculptor, and architect). It makes things easier, clearer, and prettier to read.
|
||||
|
||||
## Technical Writing
|
||||
|
||||
Technical writing, or the literature of science and technology, is hard.
|
||||
|
||||
You'll need to take a technical (usually abstract) topic and explain it in a clear, accurate, and objective manner.
|
||||
|
||||
You'll likely go through several rounds of proofreading and editing before you're happy with the result.
|
||||
|
||||
## Outline
|
||||
|
||||
Before you begin writing, create an outline of the topic and think about any coding examples you'll use (if applicable).
|
||||
|
||||
This helps to organize your thoughts and make the writing process easier.
|
||||
|
||||
## Intro
|
||||
|
||||
The introduction paragraph should only be 1-2 sentences long and be a simple explanation of the main topic. It should limit the use of any links to other Guide articles, as they can be distracting.
|
||||
|
||||
## Content
|
||||
|
||||
Keep paragraphs short (around 1-4 sentences). People are more likely to read several short paragraphs over a wall of text.
|
||||
|
||||
## Clarity
|
||||
|
||||
Articles should be written with short, clear sentences, and use as little jargon as necessary.
|
||||
|
||||
All jargon should be defined immediately in plain English.
|
||||
|
||||
## Voice
|
||||
|
||||
Use active voice instead of passive voice. Generally, it's a stronger and more straightforward way to communicate a subject. For example:
|
||||
|
||||
### Passive
|
||||
|
||||
The `for` loop in JavaScript is used by programmers to...
|
||||
|
||||
### Active
|
||||
|
||||
Programmers use the `for` loop in JavaScript to...
|
||||
|
||||
## Point of View
|
||||
|
||||
Text should use the second person ("you") to help to give it a conversational tone.
|
||||
|
||||
This way, the text and instructions seem to speak directly to the camper reading it.
|
||||
|
||||
Try to avoid using the first person ("I", "we", "let's", and "us").
|
||||
|
||||
## Abbreviations
|
||||
|
||||
If you want to abbreviate a term in your article, write it out fully first, then put the abbreviation in parentheses.
|
||||
|
||||
For example, `"In computer science, an abstract syntax tree (AST) is ..."`
|
||||
|
||||
## Proper nouns
|
||||
|
||||
Proper nouns should use correct capitalization when possible. Below is a list of words as they should appear in Guide articles.
|
||||
|
||||
- JavaScript (capital letters in "J" and "S" and no abbreviations)
|
||||
- Node.js
|
||||
|
||||
Front-end development (adjective form with a dash) is when you working on the front end (noun form with no dash). The same goes with the back end, full stack, and many other compound terms.
|
||||
|
||||
## Third-Party Tools
|
||||
|
||||
To check for grammar and spelling, we recommend using an app like [Grammarly](https://grammarly.com) or a built in extension/plugin that checks for this within your text editor.
|
||||
|
||||
- [VS Code](https://code.visualstudio.com/) - [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)
|
||||
- [Sublime Text 3](https://www.sublimetext.com/docs/3/spell_checking.html)
|
||||
|
||||
To check your writing style, we recommend the [Hemingway App](http://www.hemingwayapp.com/).
|
||||
|
||||
There’s nothing magical about this simple tool, but it will automatically detect widely agreed-upon style issues:
|
||||
|
||||
- passive voice
|
||||
- unnecessary adverbs
|
||||
- words that have more common equivalents
|
||||
|
||||
The Hemingway App will assign a "grade level" for your writing.
|
||||
|
||||
You should aim for a grade level of 6.
|
||||
|
||||
Another tool available is the [De-Jargonizer](http://scienceandpublic.com/), originally designed for scientific communication but might help avoid overspecialized wording.
|
||||
Reference in New Issue
Block a user