[docs] configure docs site deployments

[flynnduism]

Follow up to #1840.

Currently auto-deploy of the docs website is disabled, as it was causing problematic 🔴 checks on pull requests.
Here I want to discuss and track some follow up tasks...

Deploy Process

@shashankram you had a question there around deployment and process:

Once this change is merged, does it affect how new documents are added/updated by developers or is the website generation transparent?

By default, Netlify will redeploy the site when any changes are merged to the main branch of this repo. This is automated, site contents, site menus etc are auto-generated. Any docs contents that are written in markdown under docs/content/ will be published to the site once merged in. If this approach is not desirable we could look at changing the config / workflow to suit the team preference.

One exception to this is the process to publish a new release version on the website - the steps to do so are detailed in the website README here.

---

Pull Request Checks

The default config for the site deploys added a bunch of checks (via the Netlify github app integration), which had showed up on all active PRs:

This was super annoying and confusing for the team, so we removed these checks. They were failing because at that point they were attempting to build the docs site to offer per-PR previews - but the website did not exist in the code that was being checked.

Now that the Hugo site exists inside docs/, these checks should all return ✅ . However I don't think these checks should be reinstated because they add noise to pull requests and not much value IMO. @shashankram what do you think?

---

Re-enabling Site Deploys

• Netlify Github App needs to be re-added to the repo
• Build & Deploy is stopped
• Pull Request notifications (checks) have all been removed from the Netlify config

[shashankram]

Thanks for the details @flynnduism .

Now that the Hugo site exists inside docs/, these checks should all return ✅ . However I don't think these checks should be reinstated because they add noise to pull requests and not much value IMO. @shashankram what do you think?

This seems reasonable as long as PRs are not capable of breaking the documentation on the website. I do think it would be valuable to fail PRs break the documentation website, or that do not follow the correct documentation style to be rendered on the website.

[flynnduism]

@shashankram ok I can add the Netlify notification to do this - it provides a build preview of the code changes in the PR site with success/failure status.

[shashankram]

@shashankram ok I can add the Netlify notification to do this - it provides a build preview of the code changes in the PR site with success/failure status.

Question here is whether a PR can break the website, and how we can prevent it. If the checks are going to pass normally, would adding the Netlify notification cause distraction, or are there possibilities for false alarms?

[flynnduism]

Question here is whether a PR can break the website, and how we can prevent it

• It's pretty unlikely IMO. most OSM PRs will not touch the site. The ones that do will be adding/editing content which rebuilds the site but are pretty smooth
• Edits to the design, site layout or adjusting the config (for example adding plugins, translations etc) could break the site, but that's where the Netlify PR check comes in handy

If the checks are going to pass normally, would adding the Netlify notification cause distraction

• For non-docs PRs on the project, the check will not add any value. Just confirm that the site is working.
• For adding/editing docs, the check is valuable to preview the changes and to have a sharable url to show the doc changes ahead of publishing (merging).

Are there possibilities for false alarms?

• I haven't really seen false alarms. The preview builds are pretty simple and don't run into timeouts or random failures

[shashankram]

Question here is whether a PR can break the website, and how we can prevent it

• It's pretty unlikely IMO. most OSM PRs will not touch the site. The ones that do will be adding/editing content which rebuilds the site but are pretty smooth
• Edits to the design, site layout or adjusting the config (for example adding plugins, translations etc) could break the site, but that's where the Netlify PR check comes in handy

If the checks are going to pass normally, would adding the Netlify notification cause distraction

• For non-docs PRs on the project, the check will not add any value. Just confirm that the site is working.
• For adding/editing docs, the check is valuable to preview the changes and to have a sharable url to show the doc changes ahead of publishing (merging).

Are there possibilities for false alarms?

• I haven't really seen false alarms. The preview builds are pretty simple and don't run into timeouts or random failures

Thanks, it seems like a good idea to integrate it with PRs.

[flynnduism]

The Netlify check is back in place - minimized it to one single check / notification.

Clicking the details part of the UI on the right will open a deploy preview of the PR code.