Skip to content

Latest commit

 

History

History
153 lines (107 loc) · 5.69 KB

pr-builder.rst

File metadata and controls

153 lines (107 loc) · 5.69 KB

Design of pull request builder

Background

This will focus on automatically building documentation for Pull Requests on Read the Docs projects. This is one of the most requested feature of Read the Docs. This document will serve as a design document for discussing how to implement this features.

Scope

  • Making Pull Requests work like temporary Version
  • Excluding PR Versions from Elasticsearch Indexing
  • Adding a PR Builds Tab in the Project Dashboard
  • Updating the Footer API
  • Adding Warning Banner to Docs
  • Serving PR Docs
  • Excluding PR Versions from Search Engines
  • Receiving pull_request webhook event from Github
  • Fetching data from pull requests
  • Storing PR Version build Data
  • Creating PR Versions when a pull request is opened and Triggering a build
  • Triggering Builds on new commits on a PR
  • Status reporting to Github

Fetching data from pull requests

We already get Pull request events from Github webhooks. We can utilize that to fetch data from pull requests. when a pull_request event is triggered we can fetch the data of that pull request. We can fetch the pull request by doing something similar to travis-ci. ie: git fetch origin +refs/pull/<pr_number>/merge:

Modeling pull requests as a type of version

Pull requests can be Treated as a Type of Temporary Version. We might consider adding a VERSION_TYPES to the Version model.

  • If we go with VERSION_TYPES we can add something like pull_request alongside Tag and Branch.

We should add Version and Build Model Managers for PR and Regular Versions and Builds. The proposed names for PR and Regular Version and Build Managers are external and internal.

We can then use Version.internal.all() to get all regular versions, Version.external.all() to get all PR versions.

We can then use Build.internal.all() to get all regular version builds, Build.external.all() to get all PR version builds.

Excluding PR versions from Elasticsearch indexing

We should exclude to PR Versions from being Indexed to Elasticsearch. We need to update the queryset to exclude PR Versions.

Adding a PR builds tab in the project dashboard

We can add a Tab in the project dashboard that will listout the PR Builds of that project. We can name it PR Builds.

Creating versions for pull requests

If the Github webhook event is pull_request and action is opened, this means a pull request was opened in the projects repository. We can create a Version from the Payload data and trigger a initial build for the version. A version will be created whenever RTD receives an event like this.

Triggering build for new commits in a pull request

We might want to trigger a new build for the PR version if there is a new commit on the PR. If the Github webhook event is pull_request and action is synchronize, this means a new commit was added to the pull request.

Status reporting to GitHub

We could send build status reports to Github. We could send if the build was Successful or Failed. We can also send the build URL. By this we could show if the build passed or failed on Github something like travis-ci does.

As we already have the repo:status scope on our OAuth App, we can send the status report to Github using the Github Status API.

Sending the status report would be something like this:

.. http:post:: /repos/:owner/:repo/statuses/:sha


{
    "state": "success",
    "target_url": "<pr_build_url>",
    "description": "The build succeeded!",
    "context": "continuous-documentation/read-the-docs"
}

Storing pull request docs

We need to think about how and where to store data after a PR Version build is finished. We can store the data in a blob storage.

Excluding PR versions from search engines

We should Exclude the PR Versions from Search Engines, because it might cause problems for RTD users. As users might land to a pull request doc but not the original Project Docs. This will cause confusion for the users.

Serving PR docs

We need to think about how we want to serve the PR Docs.

  • We could serve the PR Docs from another Domain.
  • We could serve the PR Docs using <pr_number> namespace on the same Domain.
    • Using pr-<pr_number> as the version slug https://<project_slug>.readthedocs.io/<language_code>/pr-<pr_number>/
    • Using pr subdomain https://pr.<project_slug>.readthedocs.io/<pr_number>/

Updating the Footer API

We need to update the Footer API to reflect the changes. We might want to have a way to show that if this is a PR Build on the Footer.

  • For regular project docs we should remove the PR Versions from the version list of the Footer.
  • We might want to send is_pr data with the Footer API response.

Adding warning banner to Docs

We need to add a warning banner to the PR Version Docs to let the users know that this is a Draft/PR version. We can use a sphinx extension that we will force to install on the PR Versions to add the warning banner.

Related issues