Skip to content

Latest commit

 

History

History
130 lines (85 loc) · 8.31 KB

contributing_site.adoc

File metadata and controls

130 lines (85 loc) · 8.31 KB
Raw

Contributing to This Site

This web site is an open-source repository of content about the Clojure programming language and its greater ecosystem, hosted at https://clojure.org.

If you wish to point out an issue in the site or propose a new page, you can do so by filing a GitHub issue at https://github.com/clojure/clojure-site/issues.

If you wish to make a contribution (typo, modification, or new content), you must become a contributor and use the processes described below:

How To Become a Contributor

Contributors must sign the Clojure Contributor Agreement prior to submitting changes. The Contributor Agreement (CA) gives Rich Hickey and the contributor joint copyright interests: the contributor retains copyrights while also granting those rights to Rich Hickey as the open source project sponsor.

The CA is derived from the Oracle Contributor Agreement (OCA), used for OpenJDK, Netbeans and OpenSolaris projects and others. There is a good OCA FAQ answering many questions.

By executing the CA, contributors protect the Clojure site content and protect the flexibility to adapt the project to the changing demands of the community. In order for the CA to be effective, the Clojure project must obtain an assignment for all contributions. Please review the CA for a complete understanding of its terms and conditions. By contributing source code or other material to Clojure, you represent that you have a CA with Rich Hickey for such contributions. In order to track contributors, you understand that your full name and username may be posted on a web page listing authorized contributors that is accessible via a public URL.

To complete the agreement, fill out and submit the Contributor Agreement (an online e-form).

Note that if you have already signed the Clojure Contributor Agreement to supply patches to the Clojure source code, you do not need to sign it again as it is the same agreement.

Submitting Small Changes

Small changes can be proposed directly in the GitHub web interface:

  1. Go to the content repository https://github.com/clojure/clojure-site

  2. Navigate to the page you wish to update under content/ - the url should match the file base name. For example, this file’s content is at https://github.com/clojure/clojure-site/blob/master/content/community/contributing_site.adoc.

  3. Click the edit (pencil) icon.

  4. Content is written using the asciidoc format, which is similar to Markdown. The Editing page lists examples of the most common things you will encounter when editing content on this site. Make your changes in the text box. You can preview your changes using the "Preview changes" tab. GitHub understands asciidoc format and will provide a formatted preview of your changes.

  5. Write a concise description of the change in the bottom section of the page then click "Propose file change". This will fork the original repository into your own version of the repository with the change applied.

  6. You will then be shown a "Comparing changes" page - all of the information should be filled out automatically and a summary of your changes will be at the bottom - this is a good time to look them over one more time. Assuming it all looks correct, you can propose the change back to the original repository by clicking "Create pull request". You’ll then be able to add a comment to the pull request itself then click "Create pull request".

Submitting Large Changes

Important
 For any major changes, please open an issue first and discuss the change before spending time on it.

If you are going to create an entirely new page or make significant changes requiring multiple commits, you will likely find it easier to work using command line tools.

To create a local environment for working on a bigger change:

  1. Fork the content repository https://github.com/clojure/clojure-site - this will create a version of the site content under your own user id.

  2. git clone the forked repository in your local terminal and cd clojure-site.

  3. git checkout -b <branchname> - create a new branch to work on your change. You’ll use this branch to submit a pull request.

  4. Make one or more commits on this branch, modifying or adding one or more files. See the section below on how to build and preview changes locally. The Editing page lists examples of the most common things you will encounter when editing content on this site.

  5. Use git push to push your changes to the branch.

  6. Go to https://github.com/username/clojure-site/tree/branchname.

  7. Click the green button to "Compare, review, and create a pull request" and proceed through the prompts to submit the pull request.

To actively contribute to the site, it’s important to keep your own fork up-to-date with this repository. To do that:

  1. Add this repository to your remote urls: git remote add upstream https://github.com/clojure/clojure-site.git.

  2. Before every contribution:

    • fetch the content of upstream: git fetch upstream ;

    • move to your master branch: git checkout master (in case you aren’t already there);

    • clean your master branch of any unplanned modifications by reseting the HEAD to the fetched branch: git reset --hard upstream/master; and

    • create a new branch as explained above: git checkout -b <branchname>

Building and Previewing Changes

When working on bigger changes it’s useful to build the site locally. The site is built using JBake.

To install JBake 2.6.5:

  1. curl -L -O https://dl.bintray.com/jbake/binary/jbake-2.6.5-bin.zip (or download this file with your browser)

  2. unzip -o jbake-2.6.5-bin.zip

  3. Add jbake-2.6.5-bin/bin to your system PATH

To build the site:

Retrieve the content:

  1. git clone https://github.com/clojure/clojure-site.git (or your own fork)

  2. cd clojure-site

Retrieve and install the current theme assets (these don’t change very often so you don’t need to do this every time):

  1. curl -O https://clojure.org/clojuretheme.zip (or download this file with your browser to the clojure-site directory)

  2. unzip -o clojuretheme.zip

Generate the pages:

  1. jbake -b - this will create the static site in the output directory

  2. To view the static files, open output/index in your browser

  3. To view a live preview, run jbake -s and go to http://localhost:8820/index

Style and Navigation Changes

We are not currently looking for changes in the overall site styling, navigation, or infrastructure. There is ongoing work in that area that will be visible in the near future.

If you have an issue in these areas, please open an issue rather than a pull request.

How Contributions are Reviewed and Deployed

After submitting a pull request, a contribution will be waiting for review.

For each pull request, one more of the reviewers will take action:

  • Mark the comment with the Reviewed label. This indicates the reviewer approves of the changes and requests that an Editor merges those changes.

  • Comment on the pull request suggesting additional changes. You may address these changes with further commits on your local branch.

  • Close the pull request with a comment indicating why the change is not appropriate.

Thanks!

Thanks for your contributions!

Terms of Use

Copyright © Rich Hickey and contributors

All documentation contained in this repository is licensed by Rich Hickey under the Eclipse Public License v1.0 unless otherwise noted.