words and images by mk swanson
 
Short Life of an Elasticsearch Pull Request

Short Life of an Elasticsearch Pull Request

How to open an issue to make an Elasticsearch doc change, craft the change to your local copy, push it to your GitHub fork, create a pull request, and merge it to the Elasticsearch project.

Prerequisites: A GitHub account and local repos. See instructions at doc guild: (https://wiki.elastic.co/display/DOC/How+we+doc) and the Elasticsearch team development process: (https://github.com/elastic/elasticsearch-team/blob/master/onboarding-and-how-we-work/development_process.md#prepare-your-development-environment)

Open new issue

If the change has not yet been added as a GitHub issue, open a new issue.


  1. Go to the list of Elasticsearch issues on GitHub. (www.github.com/elastic/elasticsearch/issues)
  2. Click New Issue.
  3. Give the issue a pithy but descriptive title using Docs: as a prefix.
  4. Select Assignees, often yourself.
  5. Select Labels.
    Include >docs.
    > Note that the :Docs label is for document infrastructure – and an area label appropriate to the feature.
  6. Clear the boilerplate text in the body of the issue.
  7. Begin the issue text with a link to the Elastic guide document you will change (www.elastic.co/guide).
  8. Quote the text to be changed.
  9. Click Submit new issue.
  10. Save the five digit issue number. Reference it on the commit and pull request to tie it to this issue.

Edit doc on local repo

Open the document to be changed on your local Elasticsearch repo to make the desired changes.

  1. At a terminal prompt, use the cd command to go to your copy of the Elasticsearch repo.
    For example:
    cd documents/gitw/elasticsearch
    > To see your repo and fork, use the command git remote -v
    > If you are not in the correct branch, use the command git checkout.
    For example: git checkout master
  2. To ensure your repo is up to date, use the git pull command.
    git pull origin master Origin is the default name for the remote. If you’ve given it another name, use that.
    2.5 Create pull request branch. git checkout -b kat257-slicingsupport-26114
  3. In a text editor, open the doc to be changed. Use the URL structure as a guide to find the document in the repo.
  4. Edit the doc, retaining or recreating any links or anchors in the text. See Asciidoc cheatsheet: (https://powerman.name/doc/asciidoc)
  5. Save your edits.

Verify change

  1. At a terminal prompt: docbldes --open. The reference will appear – after a short wait – in a web page.
  2. Verify changed text and links.
  3. Close reference in terminal using ^C.

Commit changes locally

  1. At a terminal prompt, use the command git commit. This opens COMMIT_EDITMSG in the terminal window.
    git commit -a
    To commit only the selected file, use the full path and file name instead of -a.
    > You can also configure your terminal to use a text editor.
    > In some cases, you might squash and merge before sending your commit to GitHub.
  2. Verify the changes are correct.
    • message
    • commiter
    • branch
    • file name of changed file
  3. Write commit message at the top of COMMIT_EDITMSG.
    Begin message with [DOCS]. Write a brief account of the changes. At the end, add Closes #00000using the issue number you saved when opening a new issue.
    For example: [DOCS] Edited intro sentence for clarity. Closes #39865
  4. Save.
  5. See the commit using git log.

Rebase from Elasticsearch repo

  1. To roll your commit on top of the Elasticsearch repo, use the rebase command.
    git pull --rebase origin master
    > To see diagrams of rebasing and understand why you want it, see (https://git-scm.com/book/en/v2/Git-Branching-Rebasing).

Push to branch on your fork

Copy the change you’ve made from your local repo to the appropriate branch on your GitHub fork of the Elasticsearch repo.
For example: git push kat257 master

Create pull request

  1. Go to the Elasticsearch repo on your GitHub fork.
    For example: (https://github.com/kat257/elasticsearch)
  2. Click Pull request link. The link is on the right under Clone or download.
    A list of changed files will be displayed. At the top, you’ll see which base and head repository are compared.
  3. Click Create pull request.
    The commit message you wrote will appear as the title for this pull request.
  4. In the request body, delete boilerplate. Add additional description ONLY if the change is complex or you are tagging others.
  5. Assign reviewers.
  6. Select the same labels as when creating the issue.
  7. Scroll to verify the diff between documents.
  8. Click Create pull request.
    The result will display that you have requested a review, and begin running build checks, including a CLA verification.
    > If you fail the CLA check, you may need to modify your git profile /gitconfig to add your name and email address, then update the pull request.

Merge to Elasticsearch

Once your review has been completed and your pull request approved, the doc will be ready to merge with the Elasticsearch repo.

  1. When approvals are complete, return to the pull request from your fork.
  2. Verify that CI checks are complete.
  3. Click Squash and merge.
  4. Click Confirm squash and merge. A notification Pull request closed displays.

Backport change to other branches

Backport these changes to other relevant branches, e.g., 7.x, 6.7.
For a different view of cherry picking, see here: Git and other commands cheatsheet#Cherrypickcommits
Generally, backport only to branches that do not require conflict resolution to merge, and no end-of-life branches. See Elastic Support Matrix.

  1. From your local repo, update metadata from the remote using git pull. (This will throw an error message after git reset --hard in repetitive backports.)
  2. Create a custom named branch locally, for example, 7.x. git checkout -b mk-issue#-newstuff-to-7.x
  3. Replace the content of the newly created branch with the remote branch using git reset --hard. git reset --hard origin/7.x
  4. Begin backport using the cherry-pick command, e.g., git cherry-pick <commit ID> to commit changes to the new local branch. (Copy commit ID from the pull request, or, while still in the pull request branch, use git log. ^C to quit the log.)
  5. Push change to your fork, e.g., git push kat257. (Add branch name to commit only that branch.)
  6. On your GitHub fork, click Compare & pull request to backport the branch.
  7. Verify that the base repo and head repo branch are the same.
  8. Delete boilerplate, then select reviewers and labels as before, adding the backport label.
  9. Click Create pull request. GitHub will indicate that you’ve requested a review, and begin running build checks.
  10. Once build checks are run and approvals are complete, click Squash and merge.