To contribute to this repository you will
fork this repository,
push changes to a branch in your fork, and then
create as a pull request
from that branch to the master branch of this repository.
Forking only needs to be done once, after which you can push changes to your fork
using the GitHub website file editor or from a local clone, as described below.
The documentation below describes common cases for contributors. If you have any questions, please do not hesitate to ask in newcomers or Documentation SIG Gitter chats. If you have any feedback about your contributor experience, please also share it with us in these channels so that we can improve our guidelines.
You can also find some newbie-friendly issues in our task trackers:
Jenkins website is largely maintained by the Jenkins documentation special interest group. This group has various communication channels which can be used to discuss contributing to the website:
Creating a fork, aka forking,
makes a personal copy of another repository.
Any changes you make in your fork of the repository will not show up on the website
until they are merged (via pull request) to the master branch of this repository.
If you are unfamiliar with how to create a fork or how forks work, see the
link:GitHub tutorial on forking.
GitHub makes it easy to add, edit, or delete individual files via their website’s 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.
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 then 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.
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.
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.
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.
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.
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
description: "Short summary for search engines and social media" # optional
opengraph:
image: /images/folder/icon.png # optional
note: "Here you can mention that this is a guest post" # optional
---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.
To see tags people have used before:
egrep -h '^- [^ ]+$' content/blog/*/*/*.adoc | sort | uniq -cThe author attribute will map your GitHub name to author information which will be displayed in the blogpost.
If this is your first time adding a blog post, please create an author file as documented in the section below.
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!
Images for blog posts should be placed in subdirectories of the 'content/images/post-images/' directory. If a blog post is describing 'feature-x' then the images might be in 'content/images/post-images/feature-x/'.
The opengraph section is optional. It allows you to define a preview of
the article for social media. The image attribute should be a PNG or JPEG image
with more than 200px in each dimension and preferred aspect ratio about 2:1. For
more information see the documentation for Facebook,
and Twitter.
The note will be shown as a note at the top of the post,
but will be omitted from the post summary on the blog front page.
It is intended for identifying posts by guest authors and posts that were also published somewhere else.
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. |
Contributor info might be needed for creating a blogpost, but it is also used in other locations to reference contributors (e.g. in GSoC projects or SIG pages).
Please also create an "contributor" 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.
You may also add an avatar image file for yourself in content/images/avatars/
with the file named yourgithubname.jpg.
You can use an image file with one of the following extensions:
.bmp, .gif, .ico, .jpg, .jpeg, .png, .svg.
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.
The documentation pages can use the same metadata (title, description, opengraph:image)
as blog posts.
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.
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.
This section will be completed when the first (or first set of) "how-to guides" are written up.
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.
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.
Jenkins project still hosts a lot of documentation pages on Jenkins Wiki. Some documentation sections in this repository are marked as "work-in-progress", and they just refer Wiki. It is recommended to move such pages to jenkins.io, and it can be done in a semi-automated way using the Jenkins Wiki Exporter tool which is based on Pandoc.
-
Open the Wiki page page you want to migrate, copy its URL
-
Go to the Jenkins Wiki Exporter web page
-
Paste the URL of the Wiki page you want to export
-
Select the export option. Use _Asciidoc for pages without images or Asciidoc Zip if you want to export images as well
-
Click the Convert button and wait till the files are generated
-
Put the content and images to the right destinations in the repository
-
Review/edit the exported file formatting
-
Remove the macro references in the top of the document
-
If the document includes "Table of contents", remove this section (or replace it by macros if needed)
-
If the Wiki includes code blocks, they will need to be manually converted. Pandoc exports them as tables
-
-
Review the content.
-
If there are any images in the exported pages, replace
todo-replace-by-actual-pathby the actual directory path (/images/…) -
Wiki pages are often outdated, and it is nice to review them before submitting (e.g. rename "slave" to "agent", "workflow" to "pipeline", "Hudson" to "Jenkins", etc.)
-
-
Commit changes, push them to your fork and create a pull request against the repository
-
Once the pull request is merged, create an
INFRAJenkins JIRA ticket to replace the content on Wiki by a link to the new jenkins.io locations
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).
Examples: content/_data/events/2017-08-28-munchen.adoc, content/_data/events/2016-12-01-san-francisco-1.adoc, content/_data/events/2019-12-01-online-meetup.adoc
Then, in that file put the following:
---
name: "<EVENT_NAME>"
location: "<LOCATION>"
date: "<DATE_TIME>"
link: "<LINK>"
---
<DESCRIPTION>-
EVENT_NAME - The name of the event. Note, this is not subject of the event, but the name. Example: "Seattle JAM", "Jenkins World 2017". Basically, take a look at the events list on https://jenkins.io/events/ as though you were trying to choose events you would go to. "August JAM" is not specific enough, but "Jenkins World 2017" is.
-
LOCATION - Location of the meetup. The recommended format is
CITY, COUNTRY, e.g. "Seattle, USA" or "Paris, France". States may be specified if needed. Use "Online" for online events like Jenkins Online Meetup -
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: "https://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.
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.
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).
In order to add a new logo, please submit a pull request,
adding a new metadata .yml file in content/_data/logo and a
new directory containing the logo assets into content/images/logos/.
Requirements to the images:
-
All submitted images are licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License
-
At least 2 images are needed: full-size PNG and another PNG which has a 256px height
-
Images should not contain the "Jenkins" or other text in the bottom like you may see on stickers. We publish only logos on the site, text can be added in credits
-
It is recommended to add PNGs without background
-
PNGs should be losslessly optimized using special tools for that, e.g. pngcrush
-
-
SVG or other vector formats can be added to the image
Each logo is identified by a unique ID (e.g. imageId), all images should be stored in a content/images/logos/${imageId}.
Metadata file for the image would be content/_data/logo/${imageId}.
Sample of such metadata file:
---
name: 'My Jenkins'
url: '/images/logos/${imageId}/${imageId}.png'
url_256: '/images/logos/${imageId}/256.png'
vector: '/images/logos/${imageId}/${imageId}.svg'
credit: 'Your Name'
credit_url: 'https://twitter.com/yourtwitteraccount'This section contains information for contributors who are interested to help with the Jenkins website maintenance.
The Jenkins website hosts various content: user and developer documentation, blog, governance materials, pages for special interest groups and sub-projects, etc. This information is maintained by multiple teams. Ownership domains are also defined in the CODEOWNERS file. Note that this file might be out of date or missing some entries, so common sense there applies.
Notable special areas:
-
Governance documents - Managed by the Governance Board
-
Jenkins core changelogs - Managed by the Jenkins core maintainers
-
Security pages and advisories under
jenkins.io/security/- Managed by the Jenkins Security Team -
Event pages under
jenkins.io/events/- Managed by event organizers, Advocacy and Outreach SIG and the Jenkins Events Officer -
SIG and sub-project pages - Managed by teams
Areas not in this file are considered as common areas and maintained by teams listed below.
There are 2 teams which maintain the majority of the website content except special areas:
-
Triage team which performs triage and reviews the submitted issues and pull requests.
-
Copy Editors team which, in addition to reviews and triage, has permissions to copy-edit and merge submitted changes.
Both teams operate under the umbrella of Jenkins Documentation Special Interest Group led by the Documentation Officer.
If you are interested to join the Triage or Copy Editors team, you can request membership in the Jenkins Developer mailing list or in the Documentation SIG channels. The request will be processed and discussed by the community, and then the documentation officer will make a decision.
Eligibility requirements:
-
Membership in both teams requires a track of contributions to the Jenkins website and/or documentation. Triage team is effectively an onboarding team for contributors interested in becoming copy editors, and this team has a low entry bar.
-
Applicants to the Copy Editors team should have a signed Contributor License Agreement.
There are many pull requests being submitted to jenkins.io every week. Reviews are driven by the community, and any contributions are always welcome. Reviews may take some time depending on availability of contributors.
Some tips for contributors:
-
Pull requests are open to public, and any GitHub user can review changes and provide feedback. If you are interested to review changes, please just do so (and thanks in advance!). No special permissions needed
-
If you need help with reviews for documentation changes, you can ask in the Documentation SIG Gitter channel.
Common area process applies when there is no special ownership or process defined. Pull requests to common areas can be merged by any Copy Editor once all of the following apply:
-
Conversations in the pull request are completed OR it is explicit that a reviewer does not block the change (often indicated by line comments attached to an approving PR review, or by using the term "nit", from "nit-picking")
-
There are enough approvals
-
For trivial changes (typo fixes, minor improvements) - 1 approval from a Copy Editor
-
For major changes - at least 2 approvals from reviewers.
-
Special areas are managed by their owners. Copy Editors should not merge substantial changes in these areas unless they get explicit sign-off from owners identified in the CODEOWNERS. Minor changes like typo fixes might be integrated by Copy Editors.
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:
|