Contributing to jQuery Foundation Web Sites
- It works for code. Open source development is collaborative, auditable, and decentralized -- all qualities that should be part of working on design and documentation as well.
- Wikis and CMSes are fraught with problems for community projects. Both
are targets for spammers, which leads to tight control over user
accounts, compounding the problem that there is only a small circle of people around
the project maintainers with the ability to work on content and design. Even if
you desperately want to start contributing to a project, it can take a while
before you encounter the right people and gain the trust to get set up with
credentials. If you're one of the people who have credentials, it's Yet Another
Login and Password to remember. Once logged in, you have to make your changes
textareaor RTE instead of where you'd really like to be working: your text editor. Then, if you actually have major changes you want to propose, you can't, because there's only one instance running, so it's no place for experimentation. Designs stagnate and bugs linger (often untracked) while the canonical store of content is trapped in a database. Better hope you've got backups in place, and that you don't ever want to work while you don't have an internet connection.
- We want more people to learn how to do open source. Our users come from all backgrounds, and many come to jQuery without prior experience in the world of commits and pull requests, of local development and dependency management, of build processes and deployments. This can make contributing to jQuery seem a remote and intimidating prospect: "Not only do I have to be capable of fixing a bug in jQuery, I have to figure out all this stuff too?" With open content and design, we hope to provide opportunities for all you folks who have "always wanted to get involved" learn the tools and workflows common to open source projects, while working on the types of issues you're comfortable solving.
link How It Works
link Content Repositories
Inspired by static site generators like Jekyll, each of
the sites (with some exceptions*), on
jquery.org, including this very one you're
reading, has a corresponding
repository in our GitHub organization that serves
as the canonical source of the content. Most of these repositories have a
combination of HTML and Markdown
(typically in the
pages directory), each with bits of leading metadata (JSON
or YAML, respectively). The API documentation for
QUnit is maintained as XML in the
entries directory. Assets such as images (the kind you'd put in an
not in a CSS
background-image) are kept in the
link WordPress and jquery-wp-content
Whether for production, staging, or local development, the sites are served from a WordPress network. Using a WordPress multisite setup gives us the control we need to share structure and style across all of the different sites, and provides us with dynamic features like searching and user accounts on top of the static content repositories. We've worked together with members of the WordPress Core Team to create jquery-wp-content, which provides a custom install script that sets up all the different subdomains, and a parent/child theme setup that applies across the entire network, and handles other aspects of the configuration.
We do not make any modifications to content, layout, or configuration through the WordPress Administration panels.
Each of the content repositories comes with a build process that uses the
node.js task-based build tool grunt.
grunt deploy command will use the two grunt plugins we've built
specifically for our sites,
grunt-wordpress, to process
the static content into HTML, and then synch the built output into WordPress
over XML-RPC, using the
credentials in the
config.json file in the repository, creating and editing
posts and pages mirroring the directory structure of the original source
link Deploying to Staging and Production Environments
In addition to our production environment, we also have a staging environment
for all of the sites. The URLs for the staging sites are the same as the
production URLs, except they are preceded with a
stage. prefix, e.g.,
stage.contribute.jquery.org. We use git
post-receive hooks to
automate deployment to both environments. Whenever there is a commit to the
master branch of any content repository, or
jquery-wp-content itself, the
changes are pulled onto the staging site, and the
grunt deploy runs, making
them available for immediate preview. When we are ready to deploy changes to
production, we need only tag the
repo with a valid semver, and the same process takes
place in production.
For api.jqueryui.com and api.jquerymobile.com, the major and minor versions
have to match the code version the site documents. Use
patch to update the
documentation for a given major/minor release.
For other sites:
patchfor trivial changes, like typos
minorfor bigger changes, like new pages
To create a tag, use
npm version [major | minor | patch].
Afterwards, make sure to push both version change commit and the tag:
git push --tags origin master
link How Can I Help?
link Just File Issues!
When you notice something wrong with one of our sites, or you have an idea for how something could be improved, don't keep it to yourself. Filing a Github issue on the appropriate repository is the best way to let us know what's up. We even have repositories just for tracking issues with sites that aren't managed through jquery-wp-content, such as http://bugs.jquery.com.
When you're looking at a live site, it may sometimes be a bit unclear whether
your issue should be filed on a content repository or directly on
jquery-wp-content. Typically, if
the problem has anything to do with markup or CSS, it's a
problem. If the problem lies with the actual content of the words and code
you're reading, you probably should file the issue on the content repository.
If you happen to make the "wrong" choice, however, we still appreciate the report, and
will make sure it finds its way to the right place if necessary.
link Editing and Authoring Content
If you actually want to make commits to make the fixes and improvements, then you'll need to fork the content repositories you'd like to work on. When you have changes you'd like to have reviewed for integration, submit a pull request. However, we recommend that you file issues for new "features" and significant changes before actually getting to work. For more information on maintaining your fork and strategies on commiting, see the Commits and Pull Requests guide.
You'll note that it is possible to make content changes without setting up a
local WordPress instance. You won't be able to preview your changes as they'll
appear on the site, and you won't be able to run
grunt deploy, which means
you can't be 100% sure that the content will build successfuly. We will accept
pull requests on content from users who haven't had a chance to test locally, but
encourage anyone who's planning to contribute regularly to get configured
for deploying and testing locally.
link Design and Layout
To work on the CSS, HTML, and PHP that comprise the site theme, you'll need a fork of jquery-wp-content. Again, it is possible, but discouraged, to make theming changes without configuring a local WordPress instance.
The parent theme that applies to all sites is located in the
folder. Each content site has a child theme in the
themes folder that
corresponds to the repository name, and supplies styling and templates specific
to that site.
link Local Development
In order to iterate on site content and design in the same way that jQuery team members do, we encourage anyone to set up a local WordPress instance running jquery-wp-content.
Before you get started, you'll need to have the following technologies installed on your system
These setup instructions apply to all jQuery Foundation websites with public content repositories. For the sake of the rest of this example, we'll assume you want to work on the content and style of contribute.jquery.org. Please substitute the URL of whichever site you are actually working on, as appropriate.
Once you get jquery-wp-content working right, you should be able navigate to
local.contribute.jquery.org in a browser,
and see a site that looks exactly like the live site, only without any actual articles. That's where
contribute.jquery.org content repo comes into play.
- Fork the
contribute.jquery.orgrepository on GitHub by clicking the "Fork" button.
- Clone your forked repository to wherever you'd like, except not be inside of your WordPress and
git clone https://github.com/YourUsername/contribute.jquery.org.git
- Enter the directory where you cloned the repo --
- Install grunt-cli (if you haven't already) --
npm install -g grunt-cli
- Install local build dependencies --
- Copy the
config.jsonin the same directory --
cp config-sample.json config.json
config.jsonto use the username and password for your local WordPress network
- Build and deploy the files to your local WordPress --
At this point, if you refresh your
local.contribute.jquery.org, your local
instance should be populated with all of the site content.
When working on content locally, you may find it useful to use the
grunt watch task,
which will re-deploy the site every time you edit any of the content files.
Make your changes to your the content repo or to
necessary, and keep the Commits and Pull
Requests guidelines in mind as you prepare your
link Getting Help
If you're struggling to get any part of any site working properly, or have any questions, we're here to help.
In addition, the jQuery Content Team holds a public, weekly meeting on Freenode, at 1PM Eastern time in the #jquery-meeting channel.
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.
link Site & Repository Guide
- jquery-wp-content - The WordPress configuration and themes that serve all our sites
- jquery.com - The content of jquery.com itself
- api.jquery.com - jQuery Core API documentation
- plugins.jquery.com - The jQuery Plugin Registry
- learn.jquery.com - The jQuery Learning Center
- jqueryui.com - The content of jqueryui.com itself
- api.jqueryui.com - jQuery UI API documentation
- download.jqueryui.com - The jQuery UI Download Builder
- jquerymobile.com - The content of jquerymobile.com itself
- api.jquerymobile.com - jQuery Mobile API documentation
- jquery.org - The content of jquery.org itself
- contribute.jquery.org - The content of the jQuery Contribution Hub site
- events.jquery.org - The content of our Events and Conferences site
- irc.jquery.org - The content of our IRC log and information site
link Non-conforming Sites
Some of our sites are not part of the system described in this article. Some because they are simply not yet live, others still have some transitional work still in progress, and others that can't be integrated or have been deprecated.