Readthedocs.org: Autobuild Docs for Pull Requests

[saadmk11]

Initial Discussion about the PR Builder

This project involves automatically building docs for Pull Requests in GitHub repositories.
This Issue will work as the initial discussion for completing this project.
We can extend this to other issues when required while working on this part by part.

Initial Proposal

• We already get Pull requests event from Github webhooks. So, I think there is no need to do any changes to that.
• We can fetch the pull request like travis-ci. ref: https://github.com/rtfd/readthedocs.org/issues/1340#issuecomment-456180894
  git fetch origin +refs/pull/<pr_number>/merge:
• We might consider creating versions for pull requests. we can separate the PR versions by adding a Boolean field to Version Model or adding a type to VERSION_TYPES.
• Update all the version Querysets accordingly.
• We can create a PR version when a pull request is opened. (Event Name: pull_request, Action: opened)
• We might want to triger a build for the PR version if there is a new commit in the PR. (Event Name: pull_request, Action: synchronize)
• We can delete a PR version when a pull request is closed/merged. (Event Name: pull_request, Action: closed, Merged: True/False)
• Or we might want to have a life time limit of a PR version if its not merged in a Long Time or if we do not receive webhook event for any reason.
• We need some design decisions for where to store the PR Build data.
• We might want to Exclude PR builds from Search Engines.

In this Issue we might want to discuss about:

• How we can get started on This.
• What will be the best approach to implement this.
• In which order should these be done.
• what should be the best approach to Pull the PR data to our build server.
• The changes needed to the proposal and additional requirements.
• Get the Design Decisions, Suggestions from the Team.
• The step we can follow to make the Project successful.
• What kind of issues we might face while working on this.
• How we can solve those issues that might arise while working on this.

I would like to know Everyone's Initial Thoughts about it and carry the discussion forward :)

[safwanrahman]

I think we should move to Github Apps. @saadmk11 Can you evaluate Github Apps to know if we can move to Github Apps?

[safwanrahman]

The important part is, how do we serve the documentation. Should be it in the same domain or it should be served from different domain/subdomain. Moreover, are we going to support only Github or we should also evaluate if we can support Github/Gitlab both.

[saadmk11]

The important part is, how do we serve the documentation. Should be it in the same domain or it should be served from different domain/subdomain.

@safwanrahman I was thinking we could serve the PR builds using <pr_number> namespace.
We can do something like: : https://<project_slug>.readthedocs.io/en/pr/<pr_number>/
What do you think ?

Moreover, are we going to support only Github or we should also evaluate if we can support Github/Gitlab both.

We can get started with Github and then extend to Gitlab if we can support it.

[saadmk11]

I think we should move to Github Apps. @saadmk11 Can you evaluate Github Apps to know if we can move to Github Apps?

I read briefly about Github apps from the official Documentations. Github App has many differences from the OAuth implementation that we are currently using. we would need a good amount of refactoring to implement this and it is not as flexible as our current implementation.

Github Apps Provide Built-in, centralized webhooks receive events for all repositories and organizations the app can access. Conversely, OAuth Apps require configuring a webhook for each repository and organization accessible to the user.
Read More

Which we do not want.

It needs permissions to a users repository manually.

[agjohnson]

We've decided to not block this work on migration to GitHub apps. We already have migrating to GH apps on our roadmap in a few months though, so we'll deal with the change then.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[humitos]

@saadmk11 what's the status of this issue? I think it's OK to close it, but not as stale because everything is implemented, right?

[saadmk11]

Yes, we can close this issue as everything discussed here has been implemented.

[webknjaz]

@safwanrahman @agjohnson I saw you mentioning migration to GitHub Apps earlier. This is a topic I'm interested in a lot so if there's any help with reviews of relevant PRs needed, feel free to ping me for help.

P.S. I'm developing a small framework for making GitHub Apps (something similar to Probot which is in JS) in Python. You can try out how it feels by following this tutorial: https://tutorial.octomachinery.dev/ (beware of bugs! there's some inconsistency that I haven't yet fixed in the tutorial itself).
It's Python 3.7+ so I'm not sure if it'll fit your needs but if you need any help with integration and decide to try it out, feel free to text me and I'll see what I can do here.

[stsewd]

@webknjaz thanks, I have linked your comment in our internal ticket where we are tracking the migration