Skip to content

Latest commit

 

History

History
647 lines (519 loc) · 29.2 KB

CONTRIBUTING.adoc

File metadata and controls

647 lines (519 loc) · 29.2 KB
Raw

Contributing to jenkins.io

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.

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 link: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, 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.

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.

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

Moving documentation from Jenkins Wiki

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 Pandoc tool for Wiki→Asciidoc conversion.

  1. Open the Wiki page page you want to migrate

  2. In the "…​" button in the top right corner click the View Source action. A new window will open

  3. Save the document as HTML to a temporary folder, e.g. as mypage.html

  4. Call pandoc -o mypage.adoc --extract-media=todo-replace-by-actual-path mypage.html

  5. Put the content and images to the right destinations in the repository

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

  7. Review the content.

    • If there are any images in the exported pages, replace todo-replace-by-actual-path by 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.)

  8. Commit changes and create a pull request against the repository

  9. Once the pull request is merged, replace the content on Wiki by a link to the new jenkins.io locations (use warning boxes to do that)

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'

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. There is also a Copy Editors team which performs reviews and merges, but such reviews may take some time depending on availability of contributors.

Some tips:

  • 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 in the Documentation SIG Gitter channel.

  • If you are interested to join the Copy Editors team, you can request membership in the Jenkins Developer mailing list. Such membership requires a track of contributions to Jenkins, and also a signed Contributor License Agreement

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