To contribute to this repository, follow these steps:
-
Fork this repository and ensure that you keep only the
masterbranch. -
Create a new branch from your
masterbranch and perform your work on this new branch, avoiding direct changes to themasterbranch. -
Once your work is completed and committed to your branch, push the changes to your forked repository.
-
Create a pull request (PR) from your branch to the
masterbranch of this repository.
Note that forking needs to be done only once. After forking, you can keep your fork up to date thanks to Sync fork or make further changes to your forked repository using the GitHub website file editor or by working on a local clone, as described below.
You can also open this project as a Gitpod workspace which comes pre-configured with all the tools you will need.
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 tracker:
If you found an issue that you would like to work on, you are welcome to go ahead and start contributing. Please don’t ask to be assigned to an issue, we don’t assign individuals to issues, just go ahead and start working on it. If you want to avoid having other people work on the same issue, feel free to add a comment to the issue stating that you’re working on it. If the last comment on the issue is older than a week and there is no PR linked to the issue, you can assume nobody is working on it. If you need any help, please ask in the Communication channels.
The 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.
Changes you make in your fork do not show up on the website until they are merged (via PR) to the master branch of the repository.
If you are unfamiliar with how to create a fork or how forks work, refer to the GitHub tutorial on forking.
GitHub makes it easy to add, edit, or delete individual files via their website’s File Editor. The advantage of using the file editor is that GitHub will automatically fork (if needed), push the changes to a branch, and open a PR for you. It also means you don’t need to have a local clone of your fork. The disadvantages are that you can’t verify your 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 to 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 fork and submit a PR from there.
This project uses GNU/Make and Docker to generate the fully statically jenkins.io web site. The key tool to convert 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 Curl and Docker available on your machine:
-
make --version -
curl --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.
You can run make help to see a list of all available targets.
-
all (default target) will run a full build of the site, including
prepare,generate, andarchive. This also downloads and regenerates 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 are not downloaded again unless the
cleantarget is called first. The exception beingall, which downloads and regenerates external resources (but not download dependencies because they are more bandwidth intensive). -
generate will explicitly generate static website files.
-
run runs a live-reloading development server on localhost:4242.
-
check looks for typos. It is advised to use check to examine the documentation for typos and spelling mistakes before you submit a PR.
The majority of what is considered "legacy" content is almost entirely under content/blog.
These files represent the structure 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 that 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 that make authoring documentation easier, such as "admonition blocks", which help call out specific sections, including:
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 we recommended that you refer to the quick reference to become more familiar with what is available.
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 lowercase title for your post.
For example, if you’re writing a post that you want to title "Hello World" on January 15th, 1970, you would create the file: content/blog/1970/01/1970-01-15-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 subject, such as "tutorials" or "plugins".
Tags must contain only numbers and lowercase 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-15-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, refer to the documentation for Facebook, and Twitter.
The note is shown as a note at the top of the post, but is 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 PR containing your additions.
|
Tip
|
If you’re unfamiliar with the AsciiDoc syntax, refer to this handy quick reference guide. |
Contributor info may be needed to create a blogpost, but it is also used in other locations to reference contributors, such as GSoC projects or SIG pages.
Please also create a "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.
The image should be square (e.g. 400x400 pixels) to render properly.
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 Michael Nicholson’s blog post "Beginner’s Guide to Documentation: Here’s What You Need to Know". 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.
When you add screenshots or images to documentation, there are methods to ensure that the images are focused, clear, and useful to the reader:
-
Use consistent screen dimensions: Screenshots captured within a specific range of dimensions provide consistency for both quality and the user experience. Keep screenshots between 1024 x 768 - 1440 x 900 so that displays of any size render images properly.
Several browsers offer a native way to adjust screen size and zoom percentage:
-
Focus the screenshot’s coverage: Focusing the screenshot on the relevant content, and necessary context, helps keep the screenshot relevant. If the image requires additional screen content to provide the proper context, be sure to include that information in the screenshot.
-
Compress all images: Before adding the image, you must compress the image using something like compressor.io or PNG Crush. Compressing the image is important, as this reduces the size of the image while retaining quality.
-
Be sure to use the correct macro: There are two different image macros in Asciidoc:
-
image:is used for inline images. For example, under the Performance plugin instructions, the first image is formatted as:image:jmeter/jmeter-00.png -
image::is used for block images, where the image should be a stand alone element on the page. For example, in a recent blog post the various board images are formatted as:image::/images/post-images/2023/03/03/2023-03-03-miniJen-is-alive/NanoPi_R5S-01B.png[NanoPi R5S pic from the manufacturer,500]The block image macro (
image::) adds a background/canvas to the image, so if the image is smaller, the extended background will be displayed on the page.
-
-
Provide alt text for all images: Alt text for images increases the accessibility of Jenkins documentation. Asciidoc can handle full sentence structure and formatting for alt text. Descriptive alt text is crucial for screen readers, as they provide as much clarity as possible.
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 Michael Nicholson’s blog post "Beginner’s Guide to Documentation: Here’s What You Need to Know". 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, such as forking a given repo, as the Tutorials do. A how-to guide’s content is based on the "how-to guide" description in Michael Nicholson’s blog post "Beginner’s Guide to Documentation: Here’s What You Need to Know". While there are currently no "how-to guides", 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. This content is based predominantly on the "technical reference" description in Michael Nicholson’s blog post "Beginner’s Guide to Documentation: Here’s What You Need to Know", with appropriate "discussion" (background/overview material) and general "how-to guide" (specific to the chapter/topic in question) 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 must 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 how to use Jenkins or helping 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.
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 ("discussion" material) about the subject of this chapter, such as 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 on the handbook index page and in the TOC on the left of this page when accepted.
-
After you add some topics to this chapter page, as well as additional pages of topics within a chapter as described below, we recommend that you link to these topics from within the overview to help readers find this information.
To add a page ("section") within a chapter:
-
Within the relevant chapter subdirectory, create a new
.adocfile whose name reflects your page title. You can 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. You can copy an empty_chapter.ymlfile from another subdirectory/chapter such as 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 automatically surface on the User Handbook home page (provided by
content/doc/book/index.html.haml), which will automatically appear on the handbook index page, and the TOC on the left of this page when accepted.
-
The content on this page should be predominantly "reference" material about the subject, such as more detailed information about a specific aspect of the big new feature. These pages may contain appropriate "discussion" - and "how-to guide"- like material, such as overviews and procedures, relevant to the subject to make the content more useful.
When adding text, use a sentence per line style. Asciidoc does not treat wrapped lines in text as hard line breaks when rendered on the page. This provides several advantages to the creation, modification, and review of documentation.
The sentence per line style makes it easier to read text contributions. Otherwise, sentences are broken up over multiple lines or multiple sentences are combined into one line. This also prevents text reflows, making it easier for users to apply suggestions and changes from feedback.
When writing user handbook documentation, use the present tense as much as possible. Focusing on present tense provides readers with documentation where they are performing the actions as they read. This makes the text more active and encourages more user interaction with the documentation. Use future tense only when it is necessary.
Ensure that the information you’re providing has been tested, verified, and is correct. In addition, be sure to provide sample output when providing commands or code.
Make sure you use the correct terminology from the Jenkins glossary. We have been working on updating the terminology throughout Jenkins documentation to align with the inclusive naming initiative.
|
Important
|
There are necessary exceptions in the documentation, such as internal class names that have been retained for compatibility and UI labels that have not been updated yet. For example, the changelog for Jenkins weekly 2.396 includes a bug fix with a such an exception. |
Solution pages are somewhat special because they are generally not 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 a 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. However, a "Jenkins for C/C++" page would still be relatively specific, but could easily include a section for Visual C++/Windows specific content.
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.iopage and thejenkins.iopage redirects to the preferred location. The preferred location can be changed without modifying the software 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 a 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/ or 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.
As mentioned previously in Why AsciiDoc?, AsciiDoc supports "source code" blocks which are implemented using the following syntax:
[source, bash]
----
Source code in bash here.
----In this example bash is the name of the language used.
Replace the second value with the name of the language used in your code snippet accordingly.
It is good practice to adhere to this syntax when adding code snippets to the site. For further examples of AsciiDoc source blocks, refer to the AsciiDoc Source Code Blocks Reference.
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 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:
---
title: "<EVENT_NAME>"
location: "<LOCATION>"
date: "<DATE_TIME>"
link: "<LINK>"
---
<DESCRIPTION>-
EVENT_NAME: The name of the event. Note, this is not the subject of the event, but the name. Examples: "Seattle JAM", "DevOps World 2022". 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 "DevOps World 2022" 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.
-
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 that 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 for basic content creation.
-
Haml for more advanced/custom page creation.
Adding a new page is as easy as adding a new file to the content/ directory.
Remember that the filename you choose will be the URL of your page, so ensure you have a lowercase and useful filename.
The content/index.html.haml page is one such example of a special-case, standalone page.
To have a clean URL such as "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).
To add a new logo, submit a PR, adding a new metadata .yml file in content/_data/logo and a new directory containing the logo assets into content/images/logos/.
Logo requirements:
-
All submitted images are licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License.
-
At least two images are needed: full-size PNG and another PNG that 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, such as pngcrush.
-
-
SVG or other vector formats can be added to the image.
Each logo is identified by a unique ID, such as imageId.
All images should be stored in a content/images/logos/${imageId}.
The metadata file for the image would be content/_data/logo/${imageId}.
An example of such a metadata file is:
---
name: 'My Jenkins'
url: 'logos/${imageId}/${imageId}.png'
url_256: 'logos/${imageId}/256.png'
vector: 'logos/${imageId}/${imageId}.svg'
credit: 'Your Name'
credit_url: 'https://twitter.com/yourtwitteraccount'When creating a submission for the Jenkins Books page, prepare a .yml file with the following configuration:
---
title: "Jenkins book title"
url: https://linktobook.com/123456789
author: "Author Name"
publication_year: 2015
publisher: "Jenkins book publisher"
type: Paid
image: books/cover-image.jpg
description: |-
This is a short description of the book.
Keep this to 2-3 sentences long, so there is a description but the user should check out the book for further insight.The title, author, publication_year, and publisher are standard information for all books.
The url is a link to a page where someone can purchase or download the book.
The type should be either "Paid" or "Free", depending on the cost of the book.
The book’s cover image should be placed in the images/books directory, with the name of the book used for the filename.
* Be sure to follow the same image guidelines as above.
When entering a description, summarize what the book is about and be sure that this is kept impartial. We want to provide resources without showing a bias towards any one author/publisher/etc. in particular.
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 PRs.
-
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 in joining 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 PRs 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:
-
PRs 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 are 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. PRs to common areas can be merged by any Copy Editor once all of the following apply:
-
Conversations in the PR 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.