Skip to content

Update copy on notifications for github services deprecation #5067

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jan 8, 2019
Merged

Update copy on notifications for github services deprecation #5067

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3c732c9
Updated copy on webhooks
agjohnson Dec 27, 2018
b50af54
Update docs and point to docs in notification message
agjohnson Jan 3, 2019
f0594e5
Add year
agjohnson Jan 4, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions docs/webhooks.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@ As an example, the URL pattern looks like this: *readthedocs.org/api/v2/webhook/

Use this URL when setting up a new webhook with your provider -- these steps vary depending on the provider:

.. _webhook-integration-github:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are using http://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html to avoid doing this

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah yes. I added these as I wanted to point from our UI to these -- meaning the headings can't be allowed to change. Perhaps explicit labels is most helpful here? Also doc comments could warn doc authors though.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should only use explicit when we are linking them from another place and avoid adding them "just because" or "just in case we need it later".

That way, we will know that if it's there it's because an explicit reason.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the linter or sphinx itself can catch errors if the title is renamed. And probably is worth adding this to the docs guide https://docs.readthedocs.io/en/latest/docs.html

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this is catch automatically, I'd love it! I'm 👍 on setting this up.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can't turn on the sphinx check yet in the whole project bc of #4166 (comment) what I usually do is just check the warnings locally :)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is more than I want to tackle now. I'll leave them and we can revisit later to either throw errors or something. I don't think removing is important right now.


GitHub
~~~~~~

Expand All @@ -53,6 +55,8 @@ For a 403 error, it's likely that the Payload URL is incorrect.

.. note:: The webhook token, intended for the GitHub **Secret** field, is not yet implemented.

.. _webhook-integration-bitbucket:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, following my idea from https://github.com/rtfd/readthedocs.org/pull/5067/files#r245598268, this one and the gitlab should be removed to avoid confusions I'd say.


Bitbucket
~~~~~~~~~

Expand All @@ -63,6 +67,8 @@ Bitbucket
* Under **Triggers**, **Repository push** should be selected
* Finish by clicking **Save**

.. _webhook-integration-gitlab:

GitLab
~~~~~~

Expand All @@ -73,6 +79,8 @@ GitLab
* Leave the default **Push events** selected and mark **Tag push events** also
* Finish by clicking **Add Webhook**

.. _webhook-integration-generic:

Using the generic API integration
---------------------------------

Expand Down Expand Up @@ -136,3 +144,40 @@ Resyncing webhooks
It might be necessary to re-establish a webhook if you are noticing problems.
To resync a webhook from Read the Docs, visit the integration detail page and
follow the directions for re-syncing your repository webhook.

Troubleshooting
---------------

My project isn't automatically building
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If your project isn't automatically building, you can check your integration on
Read the Docs to see the payload sent to our servers. If there is no recent
activity on your Read the Docs project webhook integration, then it's likely
that your VCS provider is not configured correctly. If there is payload
information on your Read the Docs project, you might need to verify that your
versions are configured to build correctly.

Either way, it may help to either resync your webhook intergration (see
`Resyncing webhooks`_ for information on this process), or set up an entirely
new webhook intergration.

.. _webhook-github-services:

I was warned I shouldn't use GitHub Services
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Last year, GitHub announced that effective Jan 31st, GitHub Services will stop
working [1]_. This means GitHub will stop sending notifications to Read the Docs
for projects configured with the ``ReadTheDocs`` GitHub Service. If your project
has been configured on Read the Docs for a long time, you are most likely still
using this service to automatically build your project on Read the Docs.

In order for your project to continue automatically building, you will need to
configure your GitHub repository with a new webhook. You can use either a
connected GitHub account and a :ref:`GitHub webhook integration <webhook-integration-github>`
on your Read the Docs project, or you can use a
:ref:`generic webhook integraiton <webhook-integration-generic>` without a connected
account.

.. [1] https://developer.github.com/changes/2018-04-25-github-services-deprecation/
2 changes: 1 addition & 1 deletion readthedocs/projects/notifications.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ class DeprecatedWebhookEndpointNotification(Notification):

name = 'deprecated_webhook_endpoint'
context_object_name = 'project'
subject = 'Project {{ project.name }} is using a deprecated webhook'
subject = '{{ project.name }} project webhook needs to be updated'
send_email = False
email_period = timedelta(days=7)
level = REQUIREMENT
Expand Down
9 changes: 5 additions & 4 deletions readthedocs/templates/projects/notifications/deprecated_webhook_endpoint_email.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
<p>Just a heads up, your project {{ project.name }} has configured a <em>DEPRECATED</em> webhook to trigger new builds and should be upgraded. Projects hitting these deprecated webhook will stop building on Jan 1, 2019. Please, update it soon!</p>
<p>Your project, {{ project.name }}, is currently using GitHub Services to trigger builds on Read the Docs. Effective January 31, 2019, GitHub will no longer process requests using the Services feature, and so Read the Docs will not receive notifications on updates to your repository.</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

{{ project.name }} is surrounded by two commas, I guess we only need one, right?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Grammar time! {{ project.name}} would be an appositive, requiring surrounding in commas in this particular use:
http://www.chompchomp.com/terms/appositive.htm

We can avoid commas if we instead write:

Your {{ project.name }} project is currently using ...

But this is slightly awkward as {{ project.name }} could be interpreted as an adjective given the right project name -- for example, for a project named docs:

Your docs project is currently using...

And so this is less clear.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the link!


<p>To update the webhook your project is hitting, you need to go to the project's settings under your VCS service (GitHub, Bitbucket or GitLab) and remove the Read the Docs webhook from there.</p>
<p>To continue building your Read the Docs project on changes to your repository, you will need to add a new webhook on your GitHub repository. You can either connect your GitHub account and configure a GitHub webhook integration, or you can add a generic webhook integration.</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do wonder if the instructions about what the user has to do are clear and simple. I have a feeling that we are pointing the users to read more docs from the email instead of doing something actionable like: "Resync your webhook".

Maybe I'm wrong, but shouldn't work directly if the user goes to Admin -> Integrations -> Github -> Resync webhook. If that's the case, we could also generate the link to that section here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, the user might not even have an integration set up if they used GitHub Services. So there would be nothing to resync. Probably easiest to just give them full directions.


<p>Once you have done that, you need to go to your <a href="{% url "projects_integrations" project.slug %}">project's Integrations</a> under Read the Docs project's Admin, click integration and then in "Resync webhook" button.</p>
<p>You can find more information on our webhook intergrations in our documentation, at:</p>

<p>Thanks!</p>
{% comment %}Plain text link because of text version of email{% endcomment %}
<p><a href="https://docs.readthedocs.io/en/latest/webhooks.html">https://docs.readthedocs.io/en/latest/webhooks.html</a></p>
2 changes: 1 addition & 1 deletion readthedocs/templates/projects/notifications/deprecated_webhook_endpoint_site.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
Your project {{ project.name }} has configured a <em>DEPRECATED</em> webhook to trigger new builds and should be upgraded. Projects hitting these deprecated webhooks will stop building on Jan 1, 2019. <a href="{% url "projects_integrations" project.slug %}">Please, update it soon!</a>
Your project, {{ project.name }}, needs to be reconfigured in order to continue building automatically after Jan 31st. For more information, <a href="https://docs.readthedocs.io/en/latest/webhooks.html#webhook-github-services">see our documentation on webhook integrations</a>.