Skip to content

Latest commit

 

History

History
757 lines (597 loc) · 36.5 KB

CONTRIBUTING.adoc

File metadata and controls

757 lines (597 loc) · 36.5 KB
Raw

Contributing to jenkins.io

docs

Table of Contents

Getting Started

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.

Information for newcomers

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:

Communication channels

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

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 GitHub tutorial on forking.

Using GitHub to edit files

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.

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 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.

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, and archive. 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 clean target is called first. The exeception being all will download and regenerate external resources (but not download dependencies which are more bandwidth intensive).

  • generate will run site and pdfs.

  • 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.io website 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:

1970-01-01-hello-world.adoc
---
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 -c

The 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.

Adding contributor/author info

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:

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.

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. Picture should be square (ex 400x400 pixels) to render properly.

Adding documentation

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

  1. 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.

  2. 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 .haml and .adoc files located in the content/doc/developer/ directory. Read more about adding pages to this documentation in Adding a stand-alone-page.

  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. 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.

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:

  1. Add a new subdirectory (within this directory) whose name reflects your chapter title.

  2. Specify this subdirectory’s name as a new entry in the content/doc/book/_book.yml file. The position of the entry in this file determines the order in which the chapter appears in the User Handbook.

  3. Create an index.adoc file within the subdirectory you created above. Feel free to copy another chapter’s index.adoc content 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 by content/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:

  1. Within the relevant chapter subdirectory, create a new .adoc file whose name reflects your page title. Feel free to copy another section’s .adoc content as a template/starting point.

  2. Specify this .adoc file’s name as a new entry in a _chapter.yml file within this directory. Feel free to copy an empty _chapter.yml file from another subdirectory/chapter (e.g. from the glossary directory). 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 by content/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 a Redirect page

Sometimes we need a page in the site that automatically redirects us to another page. Common cases for a page redirect include:

Links from core or a plugin to commonly requested information

The Jenkins 'reverse proxy configuration' page or the 'How to report an issue' page. Jenkins includes a hyperlink to a specific jenkins.io page and the jenkins.io page redirects to the preferred location. The preferred location can be changed without modifying the sofware that includes the hyperlink.

Page replacement or removal

Sometimes a page needs to be moved or removed. When the user opens the moved page, the redirect automatically opens the new location. When the user opens the removed page, the redirect can take them to a different location or to the /404/index.html "not found" page

Redirects are implemented with a layout: redirect and the property redirect_url assigned the URL to the destination of the redirect. Redirects can be placed in any of the content locations (like projects/ and docs/). Redirects that need a shorter link are created by convention in the content/redirect/ folder

Oleg Nenashev has provided a brief video tutorial that shows how to create and test a redirect with jenkins.io.

Moving documentation from Jenkins Wiki

The Jenkins project is moving documentation pages from the Jenkins Wiki to www.jenkins.io. The Jenkins Wiki Exporter tool uses Pandoc to assist with the transition. Migrate a page from wiki.jenkins.io to www.jenkins.io with these steps:

  • Choose the page to convert from the GitHub issues and leave an issue comment that you want to convert that page

    1. Paste the URL of the Wiki page you want to export into the Jenkins Wiki Exporter

    2. Select the Asciidoc format for pages without images or Asciidoc Zip format for pages with images

    3. Click the Convert button and wait till the files are generated

    4. Place the Asciidoc content and the images in the correct repository locations

    5. Review and correct the exported file formatting

      • Remove macro references in the top of the document

      • Remove any "Table of contents" or replace it by macros if needed

      • Repair converted code blocks from Pandoc generated tables to Asciidoc code blocks

    6. Review the content

      • Replace any todo-replace-by-actual-path image paths in the exported pages with the actual images directory path (/images/…​)

      • Correct flawed terminology and outdated naming. For example, we use "agent" rather than "slave" and "pipeline" instead of "workflow")

    7. Commit changes, push them to your fork and create a pull request against the repository

    8. Once the pull request is merged, submit a pull request to the vhost.conf file in the jenkins-infra/jenkins-infra repository to redirect from wiki.jenkins.io to jenkins.io. The pull request will usually add to a subsection under the "Non plugin rewrites" section, depending on the content of the redirected page

RewriteCond %{HTTP_USER_AGENT} !^jenkins-wiki-exporter/(.*)$
RewriteRule "^/display/JENKINS/CSRF\+Protection$" "https://www.jenkins.io/doc/book/managing/security/#cross-site-request-forgery" [NE,NC,L,QSA,R=301]

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).

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:

content/_data/events/2017-08-28-san-francisco.adoc
---
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.
content/_data/events/2017-06-13-seattle.adoc
---
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 Kawaguchi

If 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:

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).

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'

Maintainer guide

This section contains information for contributors who are interested to help with the Jenkins website maintenance.

Website structure and ownership

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:

Areas not in this file are considered as common areas and maintained by teams listed below.

Teams and roles

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.

Joining the teams

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.

Reviewing changes

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.

Merging changes in common areas

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.

Merging changes in special areas

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.

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:

  1. Make changes in a local branch (for example, my_branch_name).

  2. 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 to origin/gh-pages (of your jenkins.io fork on GitHub).
    NOTE: If your local gh-pages or origin/gh-pages branches don’t exist, these will be created automatically.

  3. 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:

  • Images and other internal site links that use absolute path references (as opposed to relative paths) will appear broken or "not found".