Pull Request Builder Design Doc #5705

saadmk11 · 2019-05-16T22:34:20Z

This is the initial design Doc for the PR Builder. I would like to get some feedback and Guidance on this to carry on the project.
closes #5700
reference issue #5684

stsewd

Just left some comments to consider, it looks good 👍

We also need to decide what to do with the footer api here (all versions are listed here), maybe use a visual hint that it's a PR? (we show a red footer when the version is marked as deprecated)

docs/design/pr-builder.rst

stsewd · 2019-05-17T00:09:29Z

docs/design/pr-builder.rst

+
+We need to think about how we want to serve the PR Docs.
+we could serve the PR builds using ``<pr_number>`` namespace.
+We can do something like: ``https://<project_slug>.readthedocs.io/en/pr/<pr_number>/``


I was thinking we could sever this from another domain, malicious users could use PR's like a phishing method (since it shares the same domain).

Okay I'll add this to the Doc

stsewd · 2019-05-17T00:14:06Z

Also, you may want to follow https://docs.readthedocs.io/en/stable/docs.html#content to split lines

saadmk11 · 2019-05-17T09:08:17Z

@stsewd Thanks a lot for your Feedback. It really helped a lot. 👍 Updated the PR with the changes.

humitos

Here are my initial comments. Good work!

humitos · 2019-05-23T15:43:02Z

docs/design/pr-builder.rst

+- Deleting PR version and the build data
+- Excluding PR Versions from Search Engines
+- Serving PR Docs
+- Update the Footer API


What are the changes you have in mind here?

@humitos we should remove the PR Versions from the version list of the Footer

humitos · 2019-05-23T15:44:32Z

docs/design/pr-builder.rst

+We might consider adding a Boolean Field or ``VERSION_TYPES`` to the ``Version`` model.
+
+- If we go with Boolean Field we can add something like ``is_pull_request`` Field.
+- If we go with ``VERSION_TYPES`` we can add something like ``pull_request`` alongside Tag and Branch.


I prefer this one.

humitos · 2019-05-23T15:47:36Z

docs/design/pr-builder.rst

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


I assume that Github has an specific event/action for this. What is it?

its "action": "synchronize" I'll update the PR with this

humitos · 2019-05-23T15:50:31Z

docs/design/pr-builder.rst

+
+- A pull request is ``closed``. Github Webhook event (Action: ``closed``, Merged: ``False``)
+- A pull request is ``merged``. Github Webhook event (Action: ``closed``, Merged: ``True``)
+- A PR Version has reached its life time


I'd not focus too much on this one at first, since if we are going to use blob storage, we won't really care about keep the opened PRs documentation online.

@humitos so you are saying that we will not delete the PR versions if closed or merged? Correct me if I'm wrong:)

No. I'm saying that we should not invest time on deleting PRs after a life time reached and not merged/closed.

The first two points are correct to me.

humitos · 2019-05-23T16:02:41Z

docs/design/pr-builder.rst

+Excluding PR Versions from Elasticsearch Indexing
+-------------------------------------------------
+
+We should exclude to PR Versions from being Indexed to Elasticsearch.


I think this is the easiest way and it's fine to me.

Although, I was wondering if we want to have it indexed but excluded from the global search results. I mean, if you perform a search over a PR version documentation you probably expect that to work and return the proper results, right?

On the other hand, if you perform a search over the whole project for a particular term, you don't want to expose results from the PR versions.

What I'm saying it's probably too complicated and should not be a focus for the first implementation, though.

I agree. we can implement this after the initial implementation is shipped.

humitos · 2019-05-23T16:17:34Z

docs/design/pr-builder.rst

+
+- We could serve the PR Docs from another Domain.
+- We could serve the PR Docs using ``<pr_number>`` namespace on the same Domain.
+  ``https://<project_slug>.readthedocs.io/en/pr/<pr_number>/``


I think that if we keep our current URLs it could work. Example, https://<project_slug>.readthedocs.io/<language_code>/<version_slug>/

This way, we will stick to the language_code defined in the conf.py (ja, e.g) of that PR and we will can force the Version.slug to be pr5726 when a version is created. The resulting URL would be https://myproject.readthedocs.io/ja/pr5726/. This will interferes with branches and tags named in the same way, though.

On the other hand, single version project URLs will be https://myproject.readthedocs.io/pr5726/, which will interferes with any folder named pr5726 in the official project docs.

Another idea could be to use https://pr.<project_slug>.readthedocs.io/<pr_number>/.

I suppose that using any other approach that does not match our current mapping or adds "an special case inside our current mapping" will be complicated to adapt around all the code we have already written.

@humitos I like this one more https://myproject.readthedocs.io/ja/pr5726/. can we make the slug like this pr-5726 ?
for the second one shouldn't we have the <language_code>?
Both of them are good ideas. I'll add them in the Docs 👍

In the second case there is no reason to add the language code in the URL from my point of view.

In the first case, it's useful to keep compatibility with the rest of URL handling and just base the PR serving on the slug being pr-<number>.

humitos · 2019-05-23T16:17:37Z

docs/design/pr-builder.rst

+
+We need to think about how we want to serve the PR Docs.
+
+- We could serve the PR Docs from another Domain.


Serving from another domain will be confusing

humitos · 2019-05-23T16:19:55Z

docs/design/pr-builder.rst

+- We could serve the PR Docs using ``<pr_number>`` namespace on the same Domain.
+  ``https://<project_slug>.readthedocs.io/en/pr/<pr_number>/``
+
+Update the Footer API


I would not add this from the footer API and use an sphinx extension that we force to install on these version to add a banner similar to the warning banner mentioning that this is a draft or similar.

Okay, I'll add this on the Doc

I'm not familiar with sphinx extensions. I would like to know more and carry on this discussion on this in a new issue when we get close to implementing this.

saadmk11 · 2019-05-24T17:06:28Z

@humitos Thank you for your feedback. I have updated the PR. I have left some questions on your comments.

ericholscher

Lots of good stuff here. It feels like we're ready to get started to me.

@saadmk11 Do you already know where you want to start, or should we talk a bit more about that to figure it out?

ericholscher · 2019-05-29T21:49:35Z

docs/design/pr-builder.rst

+- We don't receive webhook event for a pull request being closed/merged
+- If a PR is stale (not merged for a long time).
+
+We need to delete the PR Version alongside the Build data from the blob storage.


I think we can just plan to keep the PR build data forever, and deal with it in the future if we have too much. I don't think that will be too big of an issue though.

Okay! removed this part from the design doc.

docs/design/pr-builder.rst

Co-Authored-By: Eric Holscher <[email protected]>

saadmk11 · 2019-05-30T09:46:50Z

@saadmk11 Do you already know where you want to start, or should we talk a bit more about that to figure it out?

We could start by updating the Version model and all the version Querysets to reflect that.

stsewd · 2019-06-03T19:16:12Z

docs/design/pr-builder.rst

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


Thinking more about this, any reason why we want to merge the PR type with the "normal" ones?

Feels like more work trying to exclude all Pull Request versions, instead we could just have something like Project.temporal_versions

I can't think of a case where we want this type listed in the same place with the normal PRs.

This would be using the same Version model, just in a different column

Then we would make the default Version manager exclude those versions, correct?

Updated the PR with Versions managers (internal, external).

saadmk11 · 2019-06-08T18:28:54Z

Updated the Design Doc with PR Builds Admin tab in the Project Dashboard proposal.

ericholscher

I'd like to get this merged, since we are now working on it. I think we're pretty good, and we can update it as we change things during implementation.

davidfischer · 2019-06-12T23:04:30Z

I realize I'm reviewing this after it is merged but I took a look at the document and it sounds good!

saadmk11 · 2019-06-13T12:47:25Z

@davidfischer Thanks :)

Pull Request Builder Design Doc Added

0628887

saadmk11 requested review from safwanrahman and a team May 16, 2019 22:34

fix

fff7a81

stsewd reviewed May 17, 2019

View reviewed changes

PR Builder Design Doc Updated

a154fea

code block update

2f34882

saadmk11 mentioned this pull request May 18, 2019

Switching to Github Apps for PR Builder #5710

Closed

Added Footer API changes to docs

8198de9

humitos reviewed May 23, 2019

View reviewed changes

PR Builder Design Doc Update

29f549e

saadmk11 added 2 commits May 24, 2019 23:24

doc lint fix

bafc77f

doc serving url design updated

ad80675

ericholscher reviewed May 29, 2019

View reviewed changes

docs/design/pr-builder.rst Show resolved Hide resolved

saadmk11 and others added 2 commits May 30, 2019 15:35

Update docs/design/pr-builder.rst

c3500ef

Co-Authored-By: Eric Holscher <[email protected]>

removed PR Version Delete doc

f1ff272

PR Builder Design Doc Updated

b6fd291

stsewd reviewed Jun 3, 2019

View reviewed changes

saadmk11 added 2 commits June 4, 2019 15:49

Version manager added to PR Builder Design Doc

a8c84f0

PR Builds Tab Design added

f605ba7

ordering updated and footer API proposal updated

9f48d3b

ericholscher approved these changes Jun 12, 2019

View reviewed changes

Remove silly contents, since I was wrong :)

0b1686d

ericholscher merged commit d36d453 into readthedocs:master Jun 12, 2019

saadmk11 deleted the pr-builder-doc branch June 12, 2019 19:10


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

		- We could serve the PR Docs from another Domain.

Pull Request Builder Design Doc #5705

Pull Request Builder Design Doc #5705

Conversation

saadmk11 commented May 16, 2019

stsewd left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stsewd commented May 17, 2019

saadmk11 commented May 17, 2019

humitos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

saadmk11 May 24, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

saadmk11 May 24, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

saadmk11 May 24, 2019 • edited Loading

Choose a reason for hiding this comment

saadmk11 commented May 24, 2019

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

saadmk11 commented May 30, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

saadmk11 commented Jun 8, 2019 • edited Loading

ericholscher left a comment

Choose a reason for hiding this comment

davidfischer commented Jun 12, 2019

saadmk11 commented Jun 13, 2019

saadmk11 May 24, 2019 •

edited

Loading

saadmk11 May 24, 2019 •

edited

Loading

saadmk11 May 24, 2019 •

edited

Loading

saadmk11 commented Jun 8, 2019 •

edited

Loading