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

docs: update how to work on guide articles on forum

Browse Source 
Co-Authored-By: Parth Parth <34807532+thecodingaviator@users.noreply.github.com>
Co-Authored-By: Manish Giri <manish.giri.me@gmail.com>
Co-authored-by: Mrugesh Mohapatra <1884376+raisedadead@users.noreply.github.com>
This commit is contained in:
Randell Dawson
2019-08-30 14:50:02 -07:00
committed by mrugesh
parent 76e1b1a4ba
commit 1dd13a5865
3 changed files with 230 additions and 382 deletions
Download Patch File Download Diff File Expand all files Collapse all files

305
docs/how-to-work-on-guide-articles.md
View File

@ -1,305 +0,0 @@
# How to work on Guide articles
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. 💛
You can:
- [Help us by Creating and Editing Guide Articles](#steps-for-creating-and-editing-guide-articles).
- [Help us reviewing pull requests for Guide Articles](#steps-for-reviewing-pull-requests-for-guide-articles)
## Steps for Creating and Editing Guide Articles
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. 📖 Read this [style guide for best practices](/docs/style-guide-for-guide-articles.md).
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/freeCodeCamp/issues) - any little bit of help counts! 😊
### [Follow these recommended guidelines from our Style guide for a compelling guide article](/docs/style-guide-for-guide-articles.md)
### 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 (_recommended_ for previewing changes)](#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:
![GIF showing the GitHub interface steps](https://cdn-images-1.medium.com/max/1395/1*qnFS6ITMwcpsiZvF5b1pHw.gif)
1. Go into the [**"guide"**](/guide) folder (located in freeCodeCamp repository), select the language you want to contribute to, and find the article stub you'd like to write or edit.
> All stubs will be in an index.md file
2. Click the <kbd>Edit this file</kbd> pencil icon and make your changes to the file in GitHub-flavored Markdown.
> If the icon is greyed out and giving you the warning "You must be on a branch to make or propose changes to this file", then you are likely on another person's tree. At the top left of the page, there is a drop down box which says "Tree: #######". Click on the drop down and change the branch to "master". The pencil icon should now be clickable.
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 an unconventional message like 'update file' or 'add index.md'
You can learn more about [why you should use 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>.
Congratulations 🎉! You have just created a pull request.
#### Working on your local machine (_recommended_ for previewing changes)
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.
##### Read these guidelines on [How to setup freeCodeCamp locally](/docs/how-to-setup-freecodecamp-locally.md)
### Getting PR Accepted
Here are a few guidelines the reviewers follow when reviewing PRs:
- there is a relevant description and title
- PR respects the [style guide](/docs/style-guide-for-guide-articles.md)
- 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
- **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/freeCodeCamp/pull/235)
#### Conflicting/Duplicate Content
A PR is considered a **duplicate** if it makes changes to the same article as another PR.
In general, a reviewer will:
1. Sort PR from the oldest
2. Search for PRs with similar content
3. Merge from the oldest to the newest
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
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
All PRs must pass the Travis CI checks before we can merge it.
If a PR breaks the build (a Travis CI check fails and shows a red "X") there are three likely sources.
You will need to fix the issue before we can merge your PR:
1. Your PR creates a new article and it's missing an `index.md` file somewhere.
- Every folder in `src/pages` needs an `index.md` file in it (and the name has to be `index.md`).
- Two likely scenarios are
- you named the new article file something other than `index.md`, or
- you created both a new folder and a sub-folder, then you wrote the new article in the sub-folder but forgot to put a stub `index.md` file in the new folder
2. Your PR creates a new folder and the folder name isn't formatted correctly.
- Your folder name should be all lowercase and formatted 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 [Style guide for writing articles](/docs/style-guide-for-guide-articles.md).
### 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/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)
Also, if you're working off a "stub" article, your changes must be substantial enough to replace the stub text.
We won't accept a PR that only adds links to the "More Information:" section.
The repository has a `Normalise.js` script that adds attributes to links, but also checks for "This is a stub..." text via a RegEx.
If found, it will revert the article text back to the generic stub text (and erase your changes).
This is intended behavior, since it allows us to update all stubs if the template stub changed for any reason.
### Getting Help
There's a community of support from a whole team of contributors, whom you can bounce ideas off of and ask for input on your writing.
Stay active in the [contributors chat room](https://gitter.im/freecodecamp/contributors) and ask lots of questions.
---
## Steps for reviewing pull requests for Guide Articles
> This section is targeted at reviewers of this repo.
## Squash and Merge
We use the <kcd>Squash and merge</kcd> option when merging the PR which keeps the commit history clean.
![GIF - Squash and merge](https://files.gitter.im/FreeCodeCamp/Contributors/56MQ/9cb8db153d7bb1b3576cd1ffc207e39d.gif)
### 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/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/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
> 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
```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
> For thanking and encouraging first-time contributors.
```markdown
Hi @username. Congrats on your first pull request (PR)! 🎉
Thank you for your contribution to the page! 👍
We're happy to accept these changes, and look forward to future contributions. 📝
```
#### Build Error
```markdown
Hey @username
So I'd love to be able to merge your changes but it looks like there is an error with the Travis CI build. ⚠️
Once you resolve these issues, I will be able to review your PR and merge it. 😊
---
> 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
> When PR is not up to date with `master` branch.
``````markdown
Hey @username
So I'd love to be able to merge your changes but it looks like there is an error with the Travis CI build. ⚠️
```bash
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/freeCodeCamp` repo.
Using the command line, you can do this in three easy steps:
```bash
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/freeCodeCamp.git` from above.
Once you sync your fork and pass the build, I will be able to review your PR and merge it. 😊
---
> Feel free to reference the [Syncing a Fork](https://help.github.com/articles/syncing-a-fork/) article on GitHub for more insight on how to keep your fork up-to-date with the upstream repository. 🔄
>
> Also, it's good practice on GitHub to write a brief description of your changes when creating a PR. 📝
``````
#### Merge Conflicts
> When PR has merge conflicts that need to be resolved.¹
```markdown
Hey @username
So I'd love to be able to merge your changes but it looks like you have some merge conflicts. ⚠️
Once you resolve these conflicts, I will be able to review your PR and merge it. 😊
---
> If you're not familiar with the merge conflict process, feel free to look over GitHub's guide on ["Resolving a merge conflict"](https://help.github.com/articles/resolving-a-merge-conflict-on-github/). 🔍️
>
> Also, it's good practice on GitHub to write a brief description of your changes when creating a PR. 📝
```
¹ If a first-time-contributor has a merge conflict maintainers will resolve the conflict for them.
#### Duplicate
> When PR is repetitive or a duplicate.
```markdown
Hey @username
It seems that similar changes have already been accepted earlier for this article you're editing, sorry about that. 😓
If you feel you have more to add, please feel free to open up a new PR.
Thanks again! 😊
---
> If you have any questions, feel free to reach out through [Gitter](https://gitter.im/FreeCodeCamp/Contributors) or by commenting below. 💬
```
#### Closing invalid pull requests
> When PR is invalid.
```markdown
Hey @username
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! 👍
```

170
docs/style-guide-for-guide-articles.md → docs/how-to-work-on-guide-topics.md
View File

@ -1,57 +1,69 @@
# Style guide for creating and editing Guide Articles
# How to work on Guide topics
We recommend the following guidelines for writing Guide articles to help you get started contributing and to create helpful articles.
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. Guide topics are located in [our forum](https://www.freecodecamp.org/forum/c/guide) under the `Guide` category.
## Title
You can [help us by Creating and Editing Guide Topics](#creating-and-editing-guide-topics).
Article titles should be as short, concise, and as to-the-point as possible.
## Creating and editing Guide topics
We want campers to quickly find the information they're looking for, and the title should reflect the main theme of the article.
Use the [forum search feature](https://www.freecodecamp.org/forum/search?expanded=true&q=%23guide) to find existing topics you want to [edit](#editing-an-existing-guide-topic) or to make sure the topic you want to create does not already exist. Whether editing or adding a new Guide topic, you should read about [styling best practices for Guide topics](#style-guide-for-creating-and-editing-guide-topics) to make your topic stand out.
Folder name is used in the URL, so only use dashes (-), numbers (0-9), and lowercase letters (a-z) for it.
### Editing an existing Guide topic
However, you can include special characters in the article title.
The Guide topics on the forum are wikis which can be edited by users. Only users with Level 1 status can edit the wikis.
1. Click the `Edit` button located at the bottom right of the post an
2. Make your desired changes using the editor.
3. Click `Save Edit`.
The titles use a special YAML front matter syntax block as shown below. These contain the information required by the build tools to create webpages for the guide articles.
### Creating a new Guide topic
These are the specific front matter requirements:
1. The front matter block should be on the first line of the file.
2. The front matter block should not have whitespaces before and after the lines.
3. The `title` keyword and the string value after the colon (`:`) must only be separated by a single space.
4. If the article is a translation from the english version, the front matter block should also have a `titleLocale` keyword with applicable translation for the english title.
1. Click the `+ New Topic` button at top of the forum.
2. Add a Topic Title.
3. Select `Guide` in the category dropdown.
3. Add your new content using the editor.
4. Click `+ Create Topic`.
Here are some examples of properly named titles:
### When do we edit or remove topics
> [`guide/english/javascript/loops/for-loop/index.md`](https://github.com/freeCodeCamp/freeCodeCamp/blob/master/guide/english/javascript/loops/for-loop/index.md)
We may change or remove a topic:
```markdown
---
title: For Loop
---
```
- if the topic title is not relevant
- if there is zero/little effort in it (e.g: copy-pasting from another source like Wikipedia)
- if it includes text copied from a copyrighted source
- if it does not respect the [Style guide for writing topics](#style-guide-for-creating-and-editing-guide-topics)
- if it does not respect the [Academic Honesty policy](https://www.freecodecamp.org/academic-honesty)
- if any of the content violates the [freeCodeCamp Code of Conduct](https://www.freecodecamp.org/news/code-of-conduct)
- if a new Guide topic wiki contains only links and no other relevant content
> [`guide/spanish/algorithms/binary-search-trees/index.md`](https://github.com/freeCodeCamp/freeCodeCamp/blob/master/guide/spanish/algorithms/binary-search-trees/index.md)
### Getting Help
```
---
title: Binary Search Trees
localeTitle: Árboles binarios de búsqueda
---
```
There's a community of support from a whole team of contributors, whom you can bounce ideas off of and ask for input on your writing.
## Modularity
Stay active in the [contributors' chat room](https://gitter.im/freecodecamp/contributors) and ask lots of questions.
Each article should explain exactly one concept, and that concept should be apparent from the article's title.
### Style guide for creating and editing Guide topics
We can reference other articles by linking to them inline, or in an "Other Resources" section at the end of the article.
We recommend the following guidelines for writing Guide topics to help you get started with contributing and creating helpful topics.
Our goal is to have thousands of articles that cover a broad range of technical topics.
#### Title
## Code Blocks
Topic titles should be as short, concise, and to-the-point as possible.
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.
We want campers to quickly find the information they're looking for, and the title should reflect the main theme of the topic.
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.
#### Modularity
Each topic should explain exactly one concept, and that concept should be apparent from the topic's title.
We can reference other topics by linking to them inline, or in an "Other Resources" section at the end of the topic.
Our goal is to have thousands of topics that cover a broad range of technical concepts.
#### Code Blocks
Campers will likely use Guide topics as a quick reference to look up syntax. Topics 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/topics/creating-and-highlighting-code-blocks/#syntax-highlighting) for many programming languages.
To use it, indicate the language after ```.
@ -92,20 +104,20 @@ The following represents two other examples using JavaScript and CSS syntax high
Please keep the following recommendations in mind:
- To ensure correct rendering, each code block 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 code blocks. However, this is currently __not__ supported by our rendering system.
- For codeblocks with no appropriate language, use a code fence (3 backticks) like ` ``` `.
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
#### Links
Use Markdown style links in your articles to link to other websites.
Use Markdown style links in your topics to link to other websites.
```markdown
[freeCodeCamp](https://www.freecodecamp.org/)
@ -122,7 +134,7 @@ Use Markdown style links in your articles to link to other websites.
> becomes
> `https://example.com/a-long/url/to-a-webpage/`
## List
#### Lists
You can make an unordered list by preceding one or more lines of text with - or *
To order your list, precede each line with a number.
@ -133,15 +145,15 @@ To order your list, precede each line with a number.
```
## Images
#### Images
We do not recommend adding images to an article unless absolutely necessary. Images hurt Web Accessibility, they are difficult to maintain and may get outdated. They are also slow to load on poor connections, thus, hurt web performance.
We do not recommend adding images to a topic unless necessary. Images hurt Web Accessibility, they are difficult to maintain and may get outdated. They are also slow to load on poor connections, thus, hurt web performance.
For including images in an article under compelling reasons, 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.
For including images in a topic under compelling reasons, 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.
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 a topic than by putting the new image in the repository.
To include the image in your article, use the appropriate markdown syntax:
To include the image in your topic, use the appropriate markdown syntax:
```markdown
![Image Title](https://url-to-image)
@ -155,11 +167,7 @@ You can even embed relevant YouTube videos.
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.
## Curriculum Challenge Solutions
When proposing a solution for a curriculum challenge related article, the full code should be given. This includes all the original seed code plus any changes needed to pass all the challenge tests.
## Attributions
#### Attributions
To minimize the potential for plagiarism and maintain integrity in this guide, it is important to give credit where necessary.
@ -171,7 +179,7 @@ Like so: <sup>1</sup>
1. freeCodeCamp - Attributions
Then, at the bottom of your article, place a
Then, at the bottom of your topic, place a
```markdown
### Sources
@ -186,7 +194,7 @@ 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
#### 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/)
@ -196,7 +204,7 @@ You can check out the [Purdue link referenced above](https://owl.english.purdue.
Typically, an attribution has a structure like the following:
> Author Last Name, Author First Name. "Article Title." *Publication.* Publisher. Date Published. Date Accessed.
> Author Last Name, Author First Name. "topic Title." *Publication.* Publisher. Date Published. Date Accessed.
If you cannot find an author or a publication date, which is common, simply omit these.
@ -206,7 +214,7 @@ Also note that instances of blatant plagiarism will be either removed or have th
Please refer to and review freeCodeCamp's [Academic Honesty Policy](https://www.freecodecamp.org/academic-honesty) before contributing.
## Resources
#### 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.
@ -216,7 +224,7 @@ If there are other Guide resources you think campers would benefit from, add the
- [A New Resource](#link)
```
## Formatting
#### Formatting
Use double quotes where applicable.
@ -224,7 +232,7 @@ Format language keywords as code - this is done with the backtick key (located t
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
Technical writing, or the literature of science and technology, is hard.
@ -232,39 +240,39 @@ You'll need to take a technical (usually abstract) topic and explain it in a cle
You'll likely go through several rounds of proofreading and editing before you're happy with the result.
## Outline
##### 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
##### 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.
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 topics, as they can be distracting.
## Content
##### Content
Keep paragraphs short (around 1-4 sentences). People are more likely to read several short paragraphs over a wall of text.
## Clarity
##### Clarity
Articles should be written with short, clear sentences, and use as little jargon as necessary.
Topics should be written in short, clear sentences, and use as little jargon as necessary.
All jargon should be defined immediately in plain English.
## Voice
##### Voice
Use active voice instead of passive voice. Generally, it's a stronger and more straightforward way to communicate a subject. For example:
### Passive
##### Passive
The `for` loop in JavaScript is used by programmers to...
### Active
##### Active
Programmers use the `for` loop in JavaScript to...
## Point of View
##### Point of View
Text should use the second person ("you") to help to give it a conversational tone.
@ -272,22 +280,22 @@ This way, the text and instructions seem to speak directly to the camper reading
Try to avoid using the first person ("I", "we", "let's", and "us").
## Abbreviations
##### Abbreviations
If you want to abbreviate a term in your article, write it out fully first, then put the abbreviation in parentheses.
If you want to abbreviate a term in your topic, 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
Proper nouns should use correct capitalization when possible. Below is a list of words as they should appear in Guide articles.
Proper nouns should use correct capitalization when possible. Below is a list of words as they should appear in Guide topics.
- JavaScript (capital letters in "J" and "S" and no abbreviations)
- Node.js
Front-end development (an adjective form with a dash) is when you're working on the front end (noun form with no dash). The same goes for the back end, full stack, and many other compound terms.
Front-end development (an adjective form with a dash) is when you're working on the front end (noun form with no dash). The same goes for the back end, full-stack, and many other compound terms.
## Third-Party Tools
#### 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.
@ -307,3 +315,23 @@ 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.
### Curriculum Challenge Hints and Solutions
If you find a problem with an existing challenge's hints/solutions topic, you can make suggestions in the comments below the main wiki post. Select moderators will review the comments and decide whether or not to include the changes in the existing topic.
#### Adding New Challenge Related Topics
Only moderators should add new hints and solutions topics when new challenges are added to the curriculum.
Take the following steps when adding a new challenge hints/solutions related topic.
1. Start by following the same steps for [creating a new topic](creating-a-new-guide-topic) but review the next for creating the title.
2. The title of the topic should start with "freeCodeCamp Challenge Guide: " concatenated with the actual title of the curriculum challenge. For example, if the challenge is named "Chunky Monkey", the topic title would be "freeCodeCamp Challenge Guide: Chunky Monkey".
3. `camperbot` should be the owner of these topics/posts, so you will need to request an admin to change the ownership of the main post to `camperbot`.
4. Once the new topic is created, a forum topic id is created. It is located at the end of the forum topic URL. This id must be added to the frontmatter of the curriculum challenge file via the normal pull request process for the `Get a Hint` button to link to the topic.
#### Guidelines for content of hints and solutions topics
When proposing a solution for a curriculum challenge related Guide topic, the full code should be given. This includes all the original seed code plus any changes needed to pass all the challenge tests.

125
docs/style-guide-for-curriculum-challenges.md
View File

@ -201,3 +201,128 @@ We want campers to achieve a flow state. We want them to build momentum and blas
Creating these challenges requires immense creativity and attention to detail. But you'll have plenty of help. You have support from a whole team of contributors, whom you can bounce ideas off of and demo your challenges to. Stay active in the [contributors room](https://gitter.im/freecodecamp/contributors) and ask lots of questions.
With your help, we can design an interactive coding curriculum that will help millions of people learn to code for years to come.
## Reply Templates for Moderators Reviewing Pull Requests
> 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
```markdown
Thank you for your contribution to the page! 👍
We are happy to accept these changes and look forward to future contributions. 🎉
```
### Thank you and congrats
> For thanking and encouraging first-time contributors.
```markdown
Hi @username. Congrats on your first pull request (PR)! 🎉
Thank you for your contribution to the page! 👍
We are happy to accept these changes and look forward to future contributions. 📝
```
### Build Error
```markdown
Hey @username
We would love to be able to merge your changes but it looks like there is an error with the Travis CI build. ⚠️
Once you resolve these issues, We will be able to review your PR and merge it. 😊
---
> 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
> When PR is not up to date with the `master` branch.
``````markdown
Hey @username
We would love to be able to merge your changes but it looks like there is an error with the Travis CI build. ⚠️
```bash
Error: ENOTDIR: not a directory, open 'src/pages/java/data-abstraction/index.md'
```
This particular error was not 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/freeCodeCamp` repo.
Using the command line, you can do this in three easy steps:
```bash
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/freeCodeCamp.git` from above.
Once you sync your fork and pass the build, We will be able to review your PR and merge it. 😊
---
> Feel free to reference the [Syncing a Fork](https://help.github.com/articles/syncing-a-fork/) article on GitHub for more insight on how to keep your fork up-to-date with the upstream repository. 🔄
>
> Also, it's good practice on GitHub to write a brief description of your changes when creating a PR. 📝
``````
### Merge Conflicts
> When PR has merge conflicts that need to be resolved.¹
```markdown
Hey @username
We would love to be able to merge your changes but it looks like you have some merge conflicts. ⚠️
Once you resolve these conflicts, We will be able to review your PR and merge it. 😊
---
> If you're not familiar with the merge conflict process, feel free to look over GitHub's guide on ["Resolving a merge conflict"](https://help.github.com/articles/resolving-a-merge-conflict-on-github/). 🔍️
>
> Also, it's good practice on GitHub to write a brief description of your changes when creating a PR. 📝
```
¹ If a first-time-contributor has a merge conflict, maintainers will resolve the conflict for them.
### Duplicate
> When PR is repetitive or a duplicate.
```markdown
Hey @username
It seems that similar changes have already been accepted earlier for this article you are editing, sorry about that. 😓
If you feel you have more to add, please feel free to open up a new PR.
Thanks again! 😊
---
> If you have any questions, feel free to reach out through [Gitter](https://gitter.im/FreeCodeCamp/Contributors) or by commenting below. 💬
```
### Closing invalid pull requests
> When PR is invalid.
```markdown
Hey @username
You have not added any content, We will be closing this PR and marking it as `invalid`. 😓️
Feel free to open another PR though! 👍
```