tugboatqa / docs Goto Github PK

We need some formal documentation about how to use the Tugboat CLI.

I'm not sure where to put this, but this is how I got the CLI up and running on my mac.

curl --remote-name https://dashboard2.tugboat.qa/cli/macos/tugboat
chmod +x ./tugboat
mv ./tugboat /usr/local/bin/

Some instructions similar to this would be helpful, but I'm not sure how to put it into the current page.

and for what it's worth, curl doesn't add the ".dms" extension like Safari does.

Topics might include:

1. How do you point a custom domain? (Use CNAME preview.tugboat.qa)
2. When using a custom domain, how do you get https working?
3. What are aliases?
4. How would you set up a Drupal Multisite installation?

• 1074: Repo configuration does not allow building of pull requests from forks - go to Build Previews for Forked Pull Requests (in Repository Settings) and enable it

(from conversation in Support Slack)

• Review/edit/confirm is all good for new site

Links to anchors with underscores are broken on https://docs.tugboat.qa/reference/tugboat-configuration/.

For example, checkout_path links to https://docs.tugboat.qa/reference/tugboat-configuration/#checkoutpath, but should link to https://docs.tugboat.qa/reference/tugboat-configuration/#checkout-path

This appears to be a difference in rendering between gitbook and hugo

Add a screenshot for read-only users; as a regular user or admin, I have no easy way to know exactly what that is. For example, does the "preview" button for previews show all configured URLs for all services, or just the first one?

• Shell
• Locally via command line
• Brute force push changes to git

With the transition to Hugo, we are losing the search feature from our 404 page. It'd be great to get that back, but it's going to take a little doing. I found an article explaining one way to do it, which looks promising.

https://codewithhugo.com/hugo-lunrjs-search-index/

• PHP out of memory issues
  - echo "memory_limit = 512M" >> /usr/local/etc/php/conf.d/my-php.ini

Create a page for Adding Google Lighthouse to your Tugboat Project, verify that this process works: https://tugboat.qa/2018/09/18/automating-google-lighthouse.html

• Add more documentation around setting up/using SSH key

Per conversation with Ben:
Visual Diffs = pixel by pixel comparison of Before and After. % calculation is a literal calculation of how many pixels have changed in the page from Before to After. If you move something at the top of the page that bumps content down, the whole page may show up as changed as a result. Consider adding info around this to the Using Visual Diffs page, and possibly Troubleshooting - i.e. why does my entire page show as changed?

• Verify that all "concept" content is explained elsewhere in the docs, and if not, expand docs
• Remove "concepts" from the site
• Add "concepts" pages to .htaccess

CLI and Background Process have already been incorporated elsewhere in docs. Figure out a place to put "Custom Environment Variables" and then remove "Advanced" from the site.

• Put "Custom environment variables" content somewhere else
• Edit links to custom-environment-variables/index.md to reflect new location
• Add "Advanced" pages to .htaccess

Here's the HTML for the logo:

https://github.com/TugboatQA/docs/blob/hugo-migration/layouts/partials/logo.html

The working doc for custom CSS is here:

https://github.com/TugboatQA/docs/blob/hugo-migration/static/css/tugboat.css

The directory for the SVGs are here:

https://github.com/TugboatQA/docs/tree/hugo-migration/static/images

• Add section about Visual Diffs
  • Visual diff based on config in the branch?

1. Create a GitHub Tugboat user
2. Grant that user access to your GitHub repo
3. Generate a token for that user
4. Log back into GitHub with your personal account
5. While on the Tugboat Dashboard for the Repository, click Repository Settings
6. Scroll down almost to the bottom until you see GitHub Comments
7. Click the Change button and add your GitHub Tugboat token there

Review/Edit docs for:

• Drupal 7
• Drupal 8
• WordPress
• Pantheon
• Static HTML
• Generic LAMP
• Import a MySql Database
• Run Functional Tests
• SimpleTest
• Warm a Page Cache
• Tenon.io Integration
• Add a phpMyAdmin Service

• Add Q about Slack integration, point out GitHub (and other provider?) Slack integrations as alternative

• Verify that all "Configuring Tugboat" content is explained elsewhere in the docs, and if not, expand docs
• Remove "Configuring Tugboat" from the site
• Add "Configuring Tugboat" pages to .htaccess

Sometimes I use Google to find docs, and several times recently I've searched for something on Google and gotten a 404:

• For consistency with other pages, break out Add repos to the project into separate sections: new project, add repos to existing project.

Review/edit Reference docs, and incorporate into docs where possible:

• Config File
• Prebuilt Service Images
• Environment Variables
• Actions and States
• Glossary

It's helpful to be able to link directly to a heading, especially with support requests. Thankfully, there's a gitbook plugin for this:

https://plugins.gitbook.com/plugin/anchors

Let's use the same favicon(s) as https://tugboat.qa

• After adding documentation to Setting-up-Tugboat -> Repository Settings -> SSH key, add links to SSH key area in Code Snippets -> Tutorial examples

• Add a paragraph (or maybe a callout?) to this section pointing out that subsequent Preview builds start at build - and/or link to build stages explained

Any URL that links to index.md doesn't open on docs.tugboat.qa

There are a couple URLs to test on this page here:

https://docs.tugboat.qa/getting-started/create-a-preview/

• Add a section about how to connect with a provider if you've already created a project

Looks like we're missing a robots.txt in this site:

$ curl -I https://docs.tugboat.qa/robots.txt
HTTP/1.1 404 Not Found
Date: Mon, 09 Apr 2018 19:09:43 GMT
Server: Apache/2.4.33 (Unix) OpenSSL/1.0.2l
Content-Type: text/html; charset=iso-8859-1

• MySQL server has gone away"
  - resolved by increasing the packet size for MySQL

• Add info about accessing Repository Settings when you’re not in the Setting Up phase

• Confirm apache redirects for removed pages/new pages in the doc site update

1. Our Drupal 8 Makefile doesn’t fix permissions on the file directories
2. Private files and exported config are typically stored outside the webroot. Since the webroot is a symlink, that can get funky.
3. IIRC, our D8 Makefile didn’t have composer install in the build target

We also should make sure that our Drupal 8 example tugboat project uses the same Makefile.

The link to the shared Makefile source is broken.

• Point ppl at Running a Background Process (from Support Slack, user running Etherpad application in development server, hence is a never-ending command)

• Missing auto-build a Preview from a PR with no Base Preview

• Add info to this page about containers being stopped and then restarted while the snapshot is taken/committed. This will kill any "sleeping" processes waiting for completion. Advice is to look at runit documentation, per Ben's response in the Support Slack.

Also, add info around this to Troubleshooting -> Fix Problem X

We are not very up-front about how these calculations are made. Let's add a section somewhere to lay it all out.

Matt pointed out in the Support Slack that developers could define variables in their config files, like so: https://gist.github.com/mettamatt/18b9febcf4c33aa7cea8b1d757d9e934#file-lighthouse_config-yml-L27

Add a note about this to docs - maybe under custom environment variables?

• Review/edit FAQ, and incorporate into docs where possible

• Add Build Previews for Forked Pull Requests under Modify settings for your GitHub, GitLab or Bitbucket Integration

By default, Tugboat will not build Previews for forked PRs. Click this setting to enable this feature. When this feature is not enabled, Forked PRs will show up as available to build, but users will get an error if they try to build them.

The Tugboat CLI documentation should explicitly state that -h, --help can be used to query a specific command for more details (i.e. the args you can use with that command, etc.)

• Add a section about viewing logs
• Create links to this section from Troubleshooting page

Revise Visual Diffs page, including:

• Organize into sections:
  • Setting up Visual Diffs
  • Using/Viewing Visual Diffs
• Add note about visualdiffs service key (linked to Setting up Services -> Service Attributes -> visualdiffs
• Pull in some of the info from the visualdiffs attribute writeup to the Visual Diffs page
• Add a section about the visual diff config being in whatever you're building (See info from Ben)
• Add note about using visualdiff under php vs. apache, etc. (see note from James)

• Failed to refresh preview
  • Tugboat Error 1064: Command Failed: Exit code (1)
  • Check Preview log for errors (1074, etc.)