Skip to content

Commit 0d2f7b6

Browse files
committed
Revamp contributing documentation and symlink it into the page directory so it displays on the public site. Break style guide apart onto its own page.
1 parent 6f37047 commit 0d2f7b6

File tree

3 files changed

+301
-128
lines changed

3 files changed

+301
-128
lines changed

CONTRIBUTING.md

Lines changed: 168 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -1,148 +1,188 @@
1-
## Before you begin
1+
---
2+
title: Contributing
3+
customFields:
4+
-
5+
key: "is_chapter"
6+
value: 0
7+
---
8+
9+
Depending on your level of experience with some of the workflows common to many
10+
open source projects, e.g., git/Github, the command line, and setting up a
11+
local development environment, contributing to this site may be a breeze or
12+
come with a bit of a learning curve. If you fit into the former group, great!
13+
Jump ahead to learn how to get started.
14+
15+
But if you think you're part of the second group, and have had trouble
16+
participating in open source because of a lack of comfort with the tools,
17+
**you're still welcome**!. Beyond providing a resource for learning jQuery, a
18+
major goal of this site is to provide an encouraging environment for you to
19+
develop these skills, while still making a contribution that matters. Many
20+
people think that the only way to get involved with a programming project like
21+
jQuery is to solve intricate bugs that require a nuanced understanding of the
22+
codebase, or to propose enhancements that may or may not be in scope with the
23+
development team's plans. The fact is that there's way more: improving
24+
documentation, working on web properties, and supporting other users are
25+
crucial aspects where more help is always needed. If you're willing to share
26+
your time and expertise to help other developers, we're willing to [help you
27+
get up to speed with the tools](#getting-help) you'll need.
28+
29+
30+
## Why Contribute?
31+
32+
If you've ever looked for help with jQuery -- or with web development in
33+
general -- you know the hunt can sometimes be challenging. It's can be a
34+
process of wading through a number of different posts until you find that
35+
article that's the right combination of trustworthy, timely, and helpful for
36+
your particular problem. And if you're one of those authors -- thanks! -- then
37+
you are probably familiar with the frustrating feeling of putting a useful tip
38+
out there, and then wondering if it's actually making its way to the people who
39+
need it, and what to do with that old post years and versions down the road.
40+
You're invited to share that energy to help us bring that ecosystem together
41+
and grow it further!
42+
43+
44+
If you've ever helped anyone, colleague or stranger, with a particular problem,
45+
then you know the value of having a reference you can quickly link to that says
46+
"here's how you do it." This site is intended to be that compendium, but
47+
there's always more to refine and add, and we need your help too!
48+
49+
## How Does It Work?
50+
51+
### Content
52+
53+
The content in this site is maintained in
54+
[this GitHub repository](http://github.com/jquery/learn.jquery.com) as a collection of
55+
[Markdown](http://daringfireball.net/projects/markdown/) files in the `page`
56+
directory. The order in which chapters and articles are presented is controlled
57+
by the [order.yml](https://github.com/jquery/learn.jquery.com/blob/master/order.yml)
58+
file.
59+
60+
### Design
61+
62+
The site's layout and design is controlled by our
63+
[`web-base-template`](http://github.com/jquery/web-base-template), a custom
64+
[WordPress](http://wordpress.org) configuration that runs (or will run in the
65+
near future) all of the sites run by the jQuery Foundation. The [master
66+
theme](https://github.com/jquery/web-base-template/tree/master/themes/jquery)
67+
controls most of the layout for all of our sites, and there is a [child
68+
theme](https://github.com/jquery/web-base-template/tree/master/themes/learn.jquery.com)
69+
that controls the templates and styles specific to the learn site.
70+
71+
[`web-base-template`](http://github.com/jquery/web-base-template) powers our sites in
72+
production and staging environments, and can set up for local development relatively easily.
73+
74+
### Build
75+
76+
The static content in the `page` directory is deployed to a
77+
[`web-base-template`](http://github.com/jquery/web-base-template) instance
78+
using [grunt](http://gruntjs.com), specifically with two grunt plugins we've created:
79+
80+
* [grunt-jquery-content](http://github.com/jquery/grunt-jquery-content) - pre-processes content in a variety of formats (HTML, Markdown, XML) into HTML, applying syntax highlighting and some simple partial support, preparing it for processing by
81+
* [grunt-wordpress](http://github.com/scottgonzalez/grunt-wordpress) - syncs static content to WordPress using [XML-RPC](http://codex.wordpress.org/XML-RPC_Support)
282

3-
You'll need to set up your development environment. Please follow the [README.md] for instructions on setting up WordPress, web-base-templates and the learn.jquery.com repo which contains the content.
483

584
## How Can I Help?
685

7-
The entire site is managed via [this Git repository](https://github.com/jquery/learn.jquery.com). If you'd like to contribute new articles, make edits to existing content, or work on the site itself, the first thing you'll need is a [fork](https://help.github.com/articles/fork-a-repo). When you have changes you'd like to have reviewed for integration into the site, submit a [pull request](http://help.github.com/send-pull-requests/).
86+
The simplest and least complicated way to help is to [file
87+
issues](http://github.com/jquery/learn.jquery.com/issues) if you notice
88+
mistakes that should be fixed, improvements that can be made, or if you have
89+
ideas for new articles. We'll use the issues to continue discussion and track
90+
progress on anything you point out.
91+
92+
If you'd like to go a step further and contribute new articles, make edits to
93+
existing ones, or work on the site itself, the first thing you'll need is a
94+
[fork](https://help.github.com/articles/fork-a-repo). When you have changes
95+
you'd like to have reviewed for integration into the site, submit a [pull
96+
request](http://help.github.com/send-pull-requests/).
97+
98+
*(If you're unfamiliar with Git, you can still contribute by editing files
99+
directly via [GitHub's in-browser
100+
editor](https://github.com/blog/905-edit-like-an-ace). But you won't be able to
101+
create new content, and you'll still need a GitHub account and a fork of this
102+
repository. So we encourage you to [learn how to use Git and
103+
GitHub](http://help.github.com/) as soon as you can.)*
8104

9-
If you're unfamiliar with Git, you can still contribute by editing files directly via [GitHub's in-browser editor](https://github.com/blog/905-edit-like-an-ace). But you won't be able to create new content, and you'll still need a GitHub account and a fork of this repository. So we encourage you to [learn how to use Git and GitHub](http://help.github.com/); it'll probably pretty useful no matter what.
105+
## Local Development
10106

11-
Here are some shortcuts to getting set up:
107+
In order to preview your changes locally, work on design/layout issues, or work on
108+
other jQuery sites' content, and generally contribute most effectively, we
109+
recommend that you set up a local development environment. You'll need
110+
111+
* [git](http://git-scm.com)
112+
* [GitHub](http://github.com) account
113+
* Local PHP/MySQL environment, e.g., [MAMP](http://www.mamp.info/en/index.html), [XAMPP](http://www.apachefriends.org/en/xampp.html)
114+
* [node.js](http://nodejs.org)
115+
116+
### Initial Deploy
117+
118+
Once you've got these major pieces in place, you'll want to get WordPress and
119+
`web-base-template` running locally by following [these
120+
instructions](https://github.com/jquery/web-base-template/blob/master/README.md).
121+
122+
If you're get everything working right, you should be able navigate to
123+
[local.learn.jquery.com](http://local.learn.jquery.com) in a browser, you
124+
should see a site that looks exactly like the [live
125+
site](http://learn.jquery.com), only without any actual articles. That's where
126+
your the `learn.jquery.com` content repo comes into play.
12127

13128
1. Fork the [repository](https://github.com/jquery/learn.jquery.com)
14-
2. Clone the repo `git clone git@github.com:<your username>/learn.jquery.com.git`
15-
3. Set up an upstream remote back to the jQuery repo 'git remote add upstream git@github.com:jquery/learn.jquery.com.git'
16-
4. Branch master into a feature branch `git branch <feature/issue name/number>`
17-
5. Move into that branch `git checkout <feature/issue name/number>`
18-
6. Work on your awesome contribution.
19-
7. Stage the files to the index in preparation for commit `git add .`
20-
8. Commit the files to your local repo `git commit -m "add a relevant message describing the change"`
21-
9. Push the files to your github repo `git push origin <feature/issue name/number>`
22-
10. Go to github.com and go to the forked repo and submit a new [pull request](https://help.github.com/articles/using-pull-requests).
129+
2. Clone the repo -- `git clone git@github.com:<your username>/learn.jquery.com.git`
130+
3. Enter the directory where you cloned the repo -- `cd learn.jquery.com`
131+
4. Set up an upstream remote back to the jQuery repo -- 'git remote add upstream git@github.com:jquery/learn.jquery.com.git'
132+
5. Install grunt (if you haven't already) -- `npm install -g grunt`
133+
6. Install local build dependencies -- `npm install`
134+
7. Copy the `config-sample.json` file to `config.json`
135+
8. Edit `config.json` to use the username and password for your local WordPress network
136+
9. Build and deploy the files to your local WordPress -- `grunt`
137+
138+
* **Windows note:** Line endings need to be Unix-style (line-feed only). Make sure your text editor creates new files with Unix-style line endings. In addition, the following setting to your git config will keep the Unix-style line endings when pulling from the repository.*
23139

24-
## Where is the content?
140+
```
141+
$ git config --global core.autocrlf true
142+
```
25143

26-
The site files are organized in a way that you can find all the content in the site in the `page` folder.
144+
At this point, if you refresh your `local.learn.jquery.com`, your local
145+
instance should be populated with all of the site content. If it isn't,
146+
or you're having trouble with any of these steps, please come and
147+
[seek out some assistance](#getting-help).
27148

28-
## How to see changes you make?
149+
### Working With Content
29150

30-
The site files are built using grunt. After making a change open up your terminal and run grunt. Tip you can run grunt watch and grunt will watch the files for changes so you don't need to continually rerun grunt after each change.
151+
Once you've gotten your environment working, here are the general steps you should follow to make your changes:
31152

32-
## How do I add a new article?
153+
1. Create a new "feature" branch based on `master` -- `git branch <feature/issue name/number>`
154+
2. Move onto that branch -- `git checkout <feature/issue name/number>`
155+
3. Work on your awesome contribution.
156+
4. As you work and want to preview your changes, use `grunt` to deploy them to the your site. You can also use `grunt watch` to have the site monitor the `page` directory for any changes and automatically have the changes deployed every time you save.
157+
5. When you're done, stage the new/modified preparation for commit -- `git add page/faq/how-do-i-add-a-new-article-to-the-learn-site.md`
158+
6. Commit the files to your local repo -- `git commit -m "add a relevant message describing the change"`
159+
7. Push the files to your GitHub remote -- `git push origin <feature/issue name/number>`
160+
8. Go to your fork on GitHub and submit a new [pull request](https://help.github.com/articles/using-pull-requests).
33161

34-
* Add the file to the right folder in the page folder.
35-
* Add the slug name (the filename without the extension) to the right area in order.yml
36-
* Run grunt
37-
* You should now be able to navigate to the file.
162+
### Adding A New Article
38163

39-
## What is the syntax used?
164+
1. Add the file to the right folder in the page folder.
165+
2. Add the slug name (the filename without the extension) to the desired location `order.yml`
166+
3. Run `grunt`
167+
4. You should now be able to navigate to the file.
40168

41-
We are using the Github flavored Markdown.
169+
### Formatting Articles
42170

43-
## Article Header Metadata
171+
Yes! Take a look at our [style guide](http://learn.jquery.com/style-guide) for
172+
more information on authoring and formatting conventions.
44173

45-
Each article should have the following header (see below as some metatags are optional):
174+
## How Will My Contribution Be Ackowledged?
46175

47-
```
48-
---
49-
title: <article title>
50-
level: [beginner|intermediate|advance]
51-
source: <url of source of the material derived>
52-
attribution:
53-
- Ralph Whitbeck <ralph@email.com>
54-
- John Paul<john@email.com>
55-
---
56-
```
176+
We will build the attribution of an article based on the git commit logs and present this information in the site.
177+
178+
## <a name="getting-help">Getting Help</a>
179+
180+
If you're struggling to get any part of the site working properly, or have any questions, we're here to help.
181+
182+
The best place to get help is on [IRC](http://en.wikipedia.org/wiki/Internet_Relay_Chat), in the #jquery-content
183+
channel on [Freenode](http://freenode.net). If you're unfamiliar with IRC, you can use the [webchat gateway](http://webchat.freenode.net/).
184+
185+
In addition, the jQuery Content Team holds a [public, weekly
186+
meetings](http://jquery.org/meeting) on Freenode, at 1PM Eastern time in the #jquery-meeting channel.
57187

58-
The `source` attibute is optional.
59-
If the article was pulled in from an outside source you also need to add an attribution tag to give credit to the original authors.
60-
61-
## How do I get credit for my contribution?
62-
63-
We will build the attribution of an article based on the git commit logs. Only use the attribution meta tag to give credit to authors outside of git for an article that was pulled in for instance.
64-
65-
## Style Guidelines
66-
67-
Content should be educational and accessible to a broad audience of developers. The primary target audience is beginning to intermediate jQuery users, with advanced jQuery users as a secondary audience. When creating content for this site, please keep one of these audiences in mind as well as the following style guidelines.
68-
69-
### Prose & Grammar
70-
71-
- Use the Oxford comma in a list of three or more items:
72-
- **Yes:** The `load`, `scroll`, and `error` events (e.g., on an `<img>` element) do not bubble.
73-
- **No:** The `load`, `scroll` and `error` events (e.g., on an `<img>` element) do not bubble.
74-
- Numbers:
75-
- Spell out numbers one under 10.
76-
- Use numerals for numbers 10 and above.
77-
- Abbreviations:
78-
- Spell out abbreviated words on first reference, followed by the abbreviation in parentheses. Use abbreviations on second reference.
79-
80-
#### Code within Prose
81-
82-
- Always use a `code` span to denote code from prose.
83-
- Methods: use a dot, followed by the method name, followed by parentheses, e.g.: The `.focus()` method is a shortcut for the `.bind('focous', handler)` in the first and second variations, and `.trigger('focus') in the third.
84-
- Properties: use a dot, followed by the property name, e.g.: `.length`.
85-
- Functions: use the function name, followed by parentheses, e.g.: `myfunction()`.
86-
87-
#### Article & Sentence Structure
88-
89-
- Use headings to break up content into easier-to-read sections. Begin headings within an article with `<h2>`.
90-
- Keep sentences short and to the point. A good rule-of-thumb is to break up any sentence longer than 21 words into two or more seperate thoughts.
91-
- Lists:
92-
- Use bulleted lists when necessary to share a series of five or more points.
93-
- Use numbered lists only when providing step-by-step instruction - note that this should be avoided.
94-
- Use a period at the end of each ordered list item, and a period or comma at the end of an unordered list item.
95-
96-
#### Spelling
97-
98-
- Use standard American English spelling.
99-
- Capitalization:
100-
- Capitalize all proper nouns.
101-
- Do not capitalize HTML elements in code examples.
102-
- Capitalize all words in a heading or sub-heading with the exception of article adjectives and the prepositions like "with," "of," or "to."
103-
- Capitalize the first word in a list.
104-
- Punctuation:
105-
- Periods and commas go inside quotation marks.
106-
- Avoid using semicolons.
107-
108-
#### Pronoun Usage
109-
110-
- Don't use "I," "me," "us," "our," "we," and gender-specific pronouns such as "him" or "she."
111-
- Use the second-person pronoun "you" when addressing the reader, and the definite article "the" when addressing code or content:
112-
- *"You will be able to foo bar after you bar the foo."*
113-
- *"Insert the paragraph after the unordered list."*
114-
115-
#### Voice & Tone
116-
117-
- Do write in clear, easy-to-understand statements.
118-
- Do write in active voice.
119-
- Do keep the audience in mind while writing.
120-
- Do write conversationally.
121-
- Do write in the second person to address the reader.
122-
- Do use the imperative mood.
123-
- Do use humor strategically. When in doubt, err on the side of formality.
124-
- Do use hyperlinks to refer readers to concepts or topics that have been covered in other sections.
125-
- Do attribute others.
126-
- Don't assume the reader will have prior knowledge of topics or concepts, especially when targeting beginner or intermediate audiences.
127-
- Don't use rhetorical questions.
128-
- Don't write in first or third person.
129-
130-
#### Linking & Referencing Content
131-
132-
- Link to relevant content within the learn.jquery.com site to refer readers to previously covered topics or concepts.
133-
- Link to the jQuery blog or API documentation when necessary.
134-
- Use inline hyperlinks to reference relevant content.
135-
- Acceptable external resources:
136-
- Mozilla Developer Network
137-
- Webplatform.org
138-
- htmldog.com
139-
140-
### Code Examples
141-
142-
- Use examples to illustrate important concepts.
143-
- Examples should indicate what the expected result will be in comments before code is presented.
144-
- Break long examples up into shorter sections to aid comprehension.
145-
- Favor "Right Way" examples over "Wrong Way" examples - there is more than one wrong way to do something, after all.e
146-
- Use good comments so that explanation within prose isn't necessary.
147-
- Test your code examples before submitting.
148-
- Use the [jQuery Core Code Style Guide](http://docs.jquery.com/JQuery_Core_Style_Guidelines) for your code examples.
188+
If IRC is not your thing, but you still want or need to get in touch, please use the site's GitHub repo or send us an e-mail to `content at jquery dot org`.

page/contributing.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../CONTRIBUTING.md

0 commit comments

Comments
 (0)