Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
258 lines (181 sloc) 9.28 KB

Contributing to the Jenkins website

Building

Mac OS X pre-requisites

Ensure you have the latest python and ruby installed using Homebrew.

% brew install python ruby

Instructions

This project uses Gradle to build, so as long as you have JDK7 or later in your path, you should be able to build the site with:

% ./gradlew assemble
Note
If you run ./gradlew -t assemble this puts Gradle into continuous build mode, where it will regenerate the site whenever a .adoc, .haml or .md file is changed.

The easiest way to run the site is with the run task:

% ./gradlew run

This will host the statically generated site at http://localhost:4242

Editing content

The majority of what is considered "legacy" content is almost entirely under content/blog. These files represent structured around the date the original stories were written in Drupal.

Adding a blog post

In order to add a new blog post, create a new file ending in .adoc (for Asciidoctor) in the appropriate content/blog/<year> directory with the full date and a lower-case title for your post. In effect, if you’re writing a post that you want to title "Hello World" on January 1st, 1970, you would create the file: content/blog/1970/1970-01-01-hello-world.adoc.

In that file you need to enter some meta-data in the following format:

1970-01-01-hello-world.adoc
---
layout: post
title: "Hello World!"
tags:
- jenkins
- timetravel
author: yourgithubname
---

This section is referred to as the front matter. The layout attribute tells the rendering engine to use the "post" layout, title and tags should be fairly self-explanitory. The "author" attribute will map your GitHub name to author information, if this is your first time adding a blog post, please also create an "author" file in content/_data/authors/ with the file named yourgithubname.adoc. The format of this file should be:

yourgithubname.adoc
---
name: "Your Display Name"
twitter: meontwitter
github: yourgithubname
---

This is an *AsciiDoc* formatted bio, but it is completely optional!
---

Only the name: and github: sections are mandatory.

Once your author file is defined, you can return to your blog post file (1970-01-01-hello-world.adoc), finish creating the "front matter" and then write your blog post!

Once you have everything ready, you may create a pull request containing your additions.

Tip
If you’re unfamiliar with the AsciiDoc syntax, please consult this handy quick reference guide.

Adding documentation

This repository holds the central documentation for the Jenkins project. The documentation can be broken down into three categories:

  1. Knowledge-base/Handbook - rich and in-depth documentation, separated into chapters covering a topic area, conceptually similar to the FreeBSD Handbook

  2. Getting Started guides - topic-specific, progressive documentation walking the reader through the topic

  3. Solution pages - topic-specific destination pages providing a high-level overview of a topic with links into getting started guides, handbook chapters, relevant plugins and multimedia related to the topic

Why AsciiDoc?

Generally speaking, all documentation should be written in AsciiDoc. While most open source contributors are familiar with Markdown it has limitations which make writing in-depth documentation with it problematic.Markdown, as opposed to GitHub flavored Markdown, does not have support for denoting what language source code might be written in. AsciiDoc supports this natively with the "source code" block:

[source, asciidoc]
\----
This is where I would _cite_ some highlighted AsciiDoc code
\----

AsciiDoc has a number of other features which can make authoring of documentation easier, such as the "admonition blocks" which help call out specific sections, such as:

NOTE: This is a notice that you should pay attention to!

CAUTION: This is a common mistake!

Becomes:

Note
This is a notice that you should pay attention to!
Caution
This is a common mistake!

There are too many other helpful macros and formatting options to list here, so it is recommended that you refer to the quick reference to become more familiar with what is available.

Adding a Handbook chapter

The different chapters for the Handbook are located in the content/doc/book/ directory and generally speaking each .adoc file represents a single chapter of the book. Chapters are automatically surfaced on the Handbook home page (provided by content/doc/book.html.haml).

Adding a Getting Started Guide

Unlike Handbook chapters, Getting Started Guides should be directed, that is to say: the sentence "Getting Started with X" should make sense. "Getting Started with Jenkins on Windows", "Getting Started with Pipeline", "Getting Started with Access Control".

These getting started guides can be placed in content/doc/ in a directory that is most appropriate for the topic, and the directory should contain the .adoc file for the Getting Started Guide, as well as any supplementary images or other assets to accompany the guide.

Tip
Writing a Getting Started Guide while authoring a Handbook chapter on the subject can help ensure your Getting Started Guide can cite more detailed documentation for how/why certain features exist, or provide a useful reference point for "advanced" features.

Adding a Solution page

Solution pages are somewhat special insofar that they are not generally AsciiDoc files, but rather Haml templates. All the solution pages are located in the content/solutions/ directory hierarchy, with some data provided for the solution pages in content/_data/solutions/.

Important
The naming of Solution page template (pipeline.html.haml) must match the data file in content/_data/solutions, e.g. pipeline.yml

New solution pages should help guide a reader to documentation and resources about a very specific topic, or use-case, on Jenkins. How specific/niche the solution pages should be requires a bit of judgement, for example "Jenkins for Visual C" is probably too niche to fill out a page with a rich set of plugins, presentations and links to documentation. A page "Jenkins for C/C" would still be relatively specific, and could easily include a section for Visual C++/Windows specific content.

Adding a stand-alone page

Encouraged formats:

Adding a new page is as easy as adding a a new file to the content/ directory. It is important to keep in mind that the filename you choose will be the URL of your page, so ensure you have a lower-case and useful filename.

The content/index.html.haml page is one such example of a special-case, standalone page.

Clean URLs

In order to have a clean URL, e.g. "https://jenkins.io/my-clean-url", you would need to create a directory with your content in it. Using the above example, I would create the directory content/my-clean-url and if I were creating an Asciidoc file, I would then create the file content/my-clean-url/index.adoc. (Advanced Haml users would create content/my-clean-url/index.html.haml).

Advanced Building

The underlying technology is awestruct which is Ruby project, but to make it easy to use we’ve wrapped these Ruby scripts with JRuby/Gradle. If you wish to circumvent using Gradle entirely, you can do so, so long as you manage your own Ruby development environment (e.g. with RVM).

Gems

Install the bundler gem and then run bundle install

Local development

The awestruct gem provides a command line interface which is very useful. If you’re using MRI (aka "CRuby", non-JRuby), just execute: ./gradlew dev and you’ll have a live-reloading webserver running on localhost:4242

In order to get a legacy version of jenkinsci.org, ./gradlew dev-legacy

Deploying on GitHub pages

There is rudimentary (as in if it doesn’t work, you’re on your own) support for publishing the static site to GitHub Pages for demonstration purposes using the Awestruct Deployer.

This requires adding a profile to content/_config/site.yml for your fork, and manually operating awestruct