23 KiB
Contributing to jenkins.io
Overview
All changes to this repository are submitted via
pull requests from a
fork of this repository
to the master branch of this repository using the usual
GitHub Flow model.
This means all changes are pushed to a branch in a fork and are then
submitted as a pull request.
Changes can be pushed to a fork via the GitHub website file editor or from a local clone.
Using GitHub to edit files
GitHub makes it easy to add, edit, or delete individual files via their website’s link:File Editor. This has the advantage of using the file editor is that GitHub will automatically fork (if needed), push the changes to a branch, and open a pull request for you. It also means you don’t need to have a local clone of your fork. The disadvantage is that you can’t verify you changes locally before creating the PR, it only works on one file at a time, and your changes are lost if you close or navigate away from the page.
Using a local clone
We generally recommend making changes in a local clone of your fork. This requires some additional tools and storage on your local machine, and you will need a bit more technical knowledge of how to use those tools. However, this will allow you work on multiple files as part of a single set of changes. You’ll save your changes in a local branch and build and review them locally. When they are ready you will push your changes to your your fork and submit a pull request from there.
Building
This project uses GNU/Make and Docker in order to generate the fully statically generated jenkins.io web site. The key tool for converting source code into the site is the Awestruct static site generator, which is downloaded automatically as part of the build process.
Ensure you have GNU/Make and Docker available on your machine:
-
make --version -
docker version
Docker must be version 17.04 or greater.
make Targets
Run make to run a full build, or make <target> using one of the targets below
to achieve specific results.
-
all (default target) will run a full build of the site, including
prepare,generate, andarchive. This will also download and regenerate external resources. -
clean will remove all build output and dependencies in preparation for a full rebuild.
-
prepare will download external dependencies and resources necessary to build the site. As an optimization to make iterating on content locally more pleasant, dependencies and resources will not be downloaded again unless the
cleantarget is called first. The exeception beingallwill download and regenerate external resources (but not download dependencies which are more bandwidth intensive). -
generate will run
siteandpdfs. -
site will explicitly generate static website files.
-
pdfs will explicitly generate new PDFs
-
run will run a live-reloading development server on localhost:4242.
-
user-site will publish the
jenkins.iowebsite to your own "GitHub Pages". While useful for review purposes this has some known issues and limitations. See Deploying jenkins.io on GitHub pages for details.
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.
Most content on this site is written up in the AsciiDoc markup language.
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 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>/<month> 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/01/1970-01-01-hello-world.adoc.
In that file you need to enter some meta-data in the following format:
---
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 will be the displayed title of the post.
tags are descriptive terms for this post.
They can be used to search for all posts for a specific or area,
such as "tutorials" or "plugins".
Tags must contain only numbers and lower-case letters.
Tags must not contain spaces.
Tags should be short, generally one or two words.
Tags containing multiple words should squash all the words together,
as in "continuousdelivery" or "jenkinsworld2017".
Dashes are allowed but should be avoided unless describing a topic that contains
dashes, such as a plugin name that contains dashes.
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:
---
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, which can be broken down into three categories:
-
Jenkins User Documentation - for people who want to use Jenkins’s existing functionality and plugin features. The documentation model that the content is based on is described in Daniele Procida’s blog post "What nobody tells you about documentation". Refer to the Jenkins User Documentation section below for details on how this content is structured.
-
Extend Jenkins Documentation - this documentation is for people who want to extend the functionality of Jenkins by developing their own Jenkins plugins. Like the Jenkins User Documentation (above), the content is based on the same documentation model. The content for this set of documentation is written up as a combination of
.hamland.adocfiles located in thecontent/doc/developer/directory. Read more about adding pages to this documentation in Adding a stand-alone-page. -
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. Be aware that some of this content might already be present in the Jenkins User / Extend Jenkins Documentation.
Jenkins User Documentation
The Jenkins User Documentation consists of the following parts:
-
Tutorials - these are step-by-step guides that teach users relatively new to Continuous Integration (CI) / Continuous Delivery (CD) concepts about how to implement their project (of a particular tech stack) in Jenkins. A tutorial’s content is based on the "tutorial" description in Daniele Procida’s blog post "What nobody tells you about documentation". Read more about Adding a Tutorial page.
-
How-to guides - these are short guides consisting of procedures to get the reader started with specific/common use-case scenarios. They could also be guides that assist with overcoming commonly encountered issues - thereby behaving as a form of knowledgebase article. A how-to guide’s content goes beyond the more general scope of a topic in the User Handbook, but these guides do not hand-hold or teach the reader using very specific scenarios (e.g. forking a given repo), as the Tutorials do. A how-to guide’s content is based on the "how-to guide" description in Daniele Procida’s blog post "What nobody tells you about documentation". While there are currently no "how-to guides" yet, this section will be added when good candidate guides arise.
-
User Handbook - rich and in-depth documentation, separated into chapters, each of which covers a given topic/feature of Jenkins. This is conceptually and structurally similar to the FreeBSD Handbook. The User Handbook covers the fundamentals on how to use Jenkins as well as content which is not explained in the Tutorials or How-to Guides (above). This content is based predominantly on the "reference" description in Daniele Procida’s blog post "What nobody tells you about documentation" blog post, with appropriate "discussion"- (i.e. background/overview material) and general "how-to guide"- (i.e. specific to the chapter/topic in question) like material. Read more about Adding User Handbook content.
-
Resources:
-
The Pipeline Syntax Reference is a link to the published syntax.adoc reference page in the User Handbook.
-
The Pipeline Steps Reference consists of Asciidoc files which are auto-generated from content within the relevant Pipeline plugin source code. Therefore, to contribute to this content, you need to edit the relevant plugin’s source code.
-
-
Recent Tutorial Blog Posts - these are a list of the most recently published blog posts presented as tutorials (and tagged with the tutorial tag).
-
Guided Tour (Deprecated) - This part of the documentation is being decommissioned in favor of the Tutorials and How-to guides parts, both of which focus more on teaching people how to use Jenkins or helping people with specific use-cases. Once all the content from the Guided Tour is sufficiently captured in those other parts, this part will be removed.
Unless existing content in the Guided Tour needs to be updated because it is incorrect or misleading (perhaps as a result of a Jenkins update), avoid making additional contributions to this part.
Adding a Tutorial page
A tutorial is presented on its own page, each of which is written up as an
.adoc file located in the content/doc/tutorials/
directory. If an .adoc file name begins with a underscore (e.g.
content/doc/tutorials/_prerequisites.adoc),
this means that the content is used as an
Asciidoc
inclusion on another page.
Adding a How-to guide page
This section will be completed when the first (or first set of) "how-to guides" are written up.
Adding User Handbook content
The different chapters for the Handbook are located in the
content/doc/book/ directory.
To add a chapter:
-
Add a new subdirectory (within this directory) whose name reflects your chapter title.
-
Specify this subdirectory’s name as a new entry in the
content/doc/book/_book.ymlfile. The position of the entry in this file determines the order in which the chapter appears in the User Handbook. -
Create an
index.adocfile within the subdirectory you created above. Feel free to copy another chapter’sindex.adoccontent as a template/starting point. The content on this page should be an overview (i.e. "discussion" material) about the subject of this chapter (e.g. some big new Jenkins feature).
Once you do this, the chapters will automatically surface on the User Handbook home page (provided bycontent/doc/book/index.html.haml), which will automatically appear here (and in the TOC on the left of this page) when accepted.
Once you do add some topics to this chapter page as well as additional pages of topics within a chapter (see below), it’s recommended that you link to these topics from within the overview (to help readers find this information).
To add a page (i.e. "section") within a chapter:
-
Within the relevant chapter subdirectory, create a new
.adocfile whose name reflects your page title. Feel free to copy another section’s.adoccontent as a template/starting point. -
Specify this
.adocfile’s name as a new entry in a_chapter.ymlfile within this directory. Feel free to copy an empty_chapter.ymlfile from another subdirectory/chapter (e.g. from theglossarydirectory). The position of the entry in this file determines the order in which the page appears within the chapter.
Once you do this, the pages will automatically surface on the User Handbook home page (provided bycontent/doc/book/index.html.haml), which will automatically appear here (and the TOC on the left of this page) when accepted.
The content on this page should be predominantly "reference" material about the subject of page (e.g. more detailed information about a specific aspect of the big new feature). These pages may contain appropriate "discussion"- and "how-to guide"-like material (i.e. overviews and procedures) relevant to the subject to make the content more useful.
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 an event
To add an event to the Jenkins event calendar, create a file in the
content/_data/events/
folder of this repo.
To create a file in this folder using the GitHub web editor, open this page in a new tab.
Name the file using the pattern <DATE>-<CITY><OPTIONAL_ID>.adoc:
-
DATE - The is the date of the event written as
YYYY-MM-DD. For a multi-day event, use the starting day. -
CITY - The name of the city in lowercase letters without modifiers/accents (only the characters "a - z") and using dashes instead of spaces. For an online JAM, the city name should be "online".
-
OPTIONAL_ID - If there is more than one event in the same city on a specific day, add an OPTIONAL_ID as a dash and a number (1-9).
Example: content/_data/events/2017-08-28-munchen.adoc
Example: content/_data/events/2016-12-01-san-francisco-1.adoc
Example: content/_data/events/2016-12-01-san-francisco-2.adoc
Then, in that file put the following:
---
name: "<EVENT_NAME>"
date: "<DATE_TIME>"
link: "<LINK>"
---
<DESCRIPTION>-
EVENT_NAME - The name of the event. Note, this is not subject of the event, but the name.
-
DATE_TIME - The date and time of the event in the format:
YYYY-MM-DDTHH:MM:00. The time should be when the event occurs in the local time zone and always using 24-hour format. For online JAMs, use Pacific Time. -
LINK - a link to a page with more event information. For meetup
-
DESCRIPTION - A description of the event in asciidoc format. This may include the name and bio of the speakers, the subjects to be presented, links to related content, or any other information that seems relevant.
The description may be written in a local language for the event, and using any unicode characters desired. If not written in a language understood by the submitter of the event, the submitter must do due diligence to make sure what is being posted is appropriate content - either by asking someone for help or using translation software.
Examples:
---
name: "Jenkins World 2017"
date: "2017-08-28T09:00:00"
link: "http://www.cvent.com/events/jenkins-world-2017/event-summary-1d623ea19a4a4af58e9a207ff0f020db.aspx"
---
Jenkins World is THE event for everything Jenkins - community, CloudBees, ecosystem, and DevOps.---
title: "Seattle JAM"
date: "2017-06-13T18:00:00"
link: "https://www.meetup.com/Seattle-Jenkins-Area-Meetup/events/240428203/"
---
Zero to Continuous Delivery with Jenkins Blue Ocean
Presenter: Kohsuke KawaguchiIf using the GitHub UI to create this file, commit the file using the "Create a new branch for this commit and start a pull request" option. If working via a local clone, commit the change, push to a branch, and start a PR as usual.
Adding a stand-alone page
Encouraged formats:
-
Asciidoctor (basic content creation) (AsciiDoc syntax quick reference)
-
Haml (more advanced/custom page) (Haml syntax reference)
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).
Deploying jenkins.io on GitHub pages
There is rudimentary support for publishing the jenkins.io website to your own
GitHub Pages
for demonstration purposes. This feature is useful if you want to show reviewers
what your changes will actually look like on the production website,
without reviewers needing to fetch and build those changes locally.
To generate your site from local changes:
-
Make changes in a local branch (for example,
my_branch_name). -
Run the command
make user-site GITHUB_USER=<your_username>, replacing<your_username>with your GitHub user name. This will regenerate the site based on your changes and push it toorigin/gh-pages(of yourjenkins.iofork on GitHub).
NOTE: If your localgh-pagesororigin/gh-pagesbranches don’t exist, these will be created automatically. -
Assuming this process completes successfully (it might initially take a while), your changes will be visible to anyone under
https://<your_username>.github.io/jenkins.io/my_branch_name.
For example, if my user name were jenkinscontributor and I were working
locally in a branch called siteredesign, I would run the command
make user-site GITHUB_USER=jenkinscontributor. When done, people would be able
to see the site with my siteredesign branch changes at the URL
https://jenkinscontributor.github.io/jenkins.io/siteredesign.
|
Warning
|
"Rudimentary support" (above) means there are a number of known issues and if anything doesn’t work, you’re on your own. Known issues/limitations:
|