[docs] Port markdown to Docsy
This CL lands copies all the documentation in /site into /site2
but also adds frontmatter to each page.
Additionally it adds a Hugo `config.toml` file.
Once the new documentation server is live the original /site
directory will be removed and /site2 will be renamed /site.
Bugs: skia:11799
Change-Id: Ic300cf5c2a2a8fa2f9acc3455251bf818cb96a52
Docs-Preview: https://skia.org/?cl=386116
Reviewed-on: https://skia-review.googlesource.com/c/skia/+/386116
Reviewed-by: Joe Gregorio <jcgregorio@google.com>
diff --git a/site2/docs/dev/chrome/_index.md b/site2/docs/dev/chrome/_index.md
new file mode 100644
index 0000000..6aa035a
--- /dev/null
+++ b/site2/docs/dev/chrome/_index.md
@@ -0,0 +1,43 @@
+
+---
+title: "Skia in Chrome"
+linkTitle: "Skia in Chrome"
+
+weight: 7
+
+---
+
+
+Changes to the Skia repository will be rolled into Chromium by the AutoRoll bot
+several times per day.
+
+If you have a Skia change that needs to be tested in Chrome, or which requires
+associated changes in that repository, see the guides in this section for tips
+on execution.
+
+For problems in Chromium related to Skia rolls:
+
+ * Go to https://autoroll.skia.org/r/skia-autoroll. Login with google.com
+ account and click the STOP button to pause new rolls.
+ * Revert the offending DEPS roll.
+ * If an obvious owner cannot be found in the list of CLs, assign to the Skia
+ Gardener, listed in the gardeners widget on https://status.skia.org and as
+ a reviewer on the roll CL.
+ * If the Skia Gardener cannot be assigned, cc them and assign the issue to hcm@.
+
+For more tips on bug triage and labeling, see the [Issue Tracker page](../../user/issue-tracker/).
+
+Branching for Chrome
+--------------------
+
+Every 6 weeks, we cut a new branch in Skia to reflect the new release branch in
+Chrome, eg. [refs/heads/chrome/m75](https://skia.googlesource.com/skia/+/chrome/m75).
+This process is simplified by running [tools/chrome_release_branch](https://skia.googlesource.com/skia/+/7a5b6ec0f6c01d3039e3ec30de6f8065ffc8aac4/tools/chrome_release_branch.py').
+This script handles creation of the branch itself, as well as associated
+housekeeping like updating the Chrome milestone number for the next release,
+setting up the [commit queue]('https://skia.googlesource.com/skia/+/infra/config/commit-queue.cfg')
+for the new branch. For example:
+
+ tools/chrome_release_branch <commit hash>
+
+
diff --git a/site2/docs/dev/chrome/blink.md b/site2/docs/dev/chrome/blink.md
new file mode 100644
index 0000000..3ad5dcf
--- /dev/null
+++ b/site2/docs/dev/chrome/blink.md
@@ -0,0 +1,93 @@
+
+---
+title: "Blink layout tests"
+linkTitle: "Blink layout tests"
+
+---
+
+
+How to land Skia changes that change Blink layout test results.
+
+Changes that affect a small number of layout test results
+---------------------------------------------------------
+Changes affecting fewer than ~20 layout tests can be rebaselined without
+special coordination with the Blink gardener using these steps:
+
+1. Prepare your Skia change, taking note of which layout tests will turn red
+ \(see http://www.chromium.org/developers/testing/webkit-layout-tests for more
+ detail on running the Blink layout tests\).
+2. Check in your code to the Skia repo.
+3. Ahead of the Skia auto roll including your change, manually push a change to the
+ Blink LayoutTests/TestExpectations [file](https://chromium.googlesource.com/chromium/src/+/master/third_party/blink/web_tests/TestExpectations), flagging tests expected to fail as a result of your change as follows:
+ foo/bar/test-name.html [ Failure Pass ] # Needs rebaseline
+
+4. Wait for the Skia roll to land successfully.
+5. Check in another change to the Blink TestExpectations file removing all the
+ skipped test expectations you add earlier, an run `git cl rebaseline` which will prompt the automatic rebaseline.
+
+
+
+Changes that affect a large number of test results
+--------------------------------------------------
+Where a 'large number' or 'many' means more than about 20.
+Follow the instructions below:
+
+In the following the term 'code suppression' means a build flag \(a\.k\.a\. define\).
+Such code suppressions should be given a name with the form SK\_IGNORE\_xxx\_FIX.
+
+Updating the version of Skia in Chromium is called a 'roll'.
+The Auto Roll Bot performs this roll multiple times per day, and can also be done manually.
+See https://chromium.googlesource.com/chromium/src/+log/master/DEPS and search for skia\-deps\-roller.
+
+### Setup
+#### Code suppression does not yet exist \- Direct method
+1. Make a change in Skia which will change many Blink layout tests.
+2. Put the change behind a code suppression.
+3. Check in the change to the Skia repository.
+4. Manually roll Skia or append the autoroll with the code suppression to
+ Chromium's 'skia/chromium\_skia\_defines\.gypi'
+
+#### Code suppression does not yet exist \- Alternate method
+1. Add code suppression to Chromium's 'skia/chromium\_skia\_defines\.gypi' before making code
+ changes in Skia.
+2. Make a change in Skia which will change many Blink layout tests.
+3. Put the change behind a code suppression.
+4. Check in the change to the Skia repository.
+5. Wait for Skia roll into Chromium.
+
+#### Code suppression exists in header
+1. Remove code suppression from header file in Chromium and add code suppression to
+ Chromium's 'skia/chromium\_skia\_defines\.gypi'.
+ The code suppression cannot be in a header file and a defined in a gyp file at the
+ same time or a multiple definition warning will be treated as an error and break
+ the Chromium build.
+
+### Rebaseline
+1. Choose a time when the Blink tree is likely to be quiet. Avoid PST afternoons in
+ particular. The bigger the change, the more important this is. Regardless,
+ determine who the Blink gardener is and notify them. You will be making the
+ Chromium\.WebKit tree very red for an extended period, and the gardener needs to
+ know that they are not expected to fix it.
+2. Create a CL removing the code suppression from Chromium's
+ skia/chromium\_skia\_defines\.gypi while simultaneously adding [ NeedsRebaseline ]
+ lines to Blink's LayoutTests/TestExpectations [file](https://chromium.googlesource.com/chromium/src/+/master/third_party/blink/web_tests/TestExpectations).
+ Then the auto rebaseline bot will take care of the work of actually checking in the
+ new images. This is generally acceptable for up to 600 or so rebaselined images.
+ Above that you might still use [ NeedsRebaseline ], but it's best to coordinate with
+ the gardener. This should go through the CQ cleanly.
+3. Be careful with tests that are already failing or flakey. These may or may not need
+ to be rebaselined and flakey tests should not be removed from TestExpectations
+ regardless. In such cases revert the TestExpectations changes before committing.
+4. If you are not the one handling the cleanup step, please open a Skia Issue of the
+ form
+ Title: "Remove code suppression SK\_IGNORE\_xxx\_FIX\."
+ Comment: "Code suppression SK\_IGNORE\_xxx\_FIX rebaselined with Blink revision
+ 123456\." and assign it to the individual responsible for the cleanup step.
+
+### Cleanup
+1. Remove the now unused old code from Skia and any defines which were introduced
+ to suppress the new code.
+2. Check in the cleanup change to the Skia repository.
+3. Wait for Skia roll into Chromium.
+
+
diff --git a/site2/docs/dev/chrome/changes.md b/site2/docs/dev/chrome/changes.md
new file mode 100644
index 0000000..1a1a5f2
--- /dev/null
+++ b/site2/docs/dev/chrome/changes.md
@@ -0,0 +1,41 @@
+
+---
+title: "Chrome changes"
+linkTitle: "Chrome changes"
+
+---
+
+
+If your change modifies the Skia API, you may also need to land a change in Chromium.
+
+The strategy you use to synchronize changes in the Skia and Chromium
+repositories may differ based on the nature of the change, but in general, we
+recommend using build flag suppressions \(defines\)\.
+We also prefer making the old code path opt-in where possible.
+
+Method 1 \(preferred\) \- Make the old code path opt\-in for Chromium
+
+ * Add new code to Skia, leaving the old code in place.
+ * Deprecate the old code path so that it must be enabled with a flag such as
+ 'SK_SUPPORT_LEGACY_XXX'.
+ * Synchronize the above changes in Skia with a Chromium commit to
+ 'skia/skia_common.gypi' or 'skia/config/SkUserConfig.h' to enable the
+ deprecated Skia API.
+ * Note that the code suppression cannot exist in both the header file and
+ the gyp file, it should only reside in one location.
+ * Test the new or updated Skia API within Chromium.
+ * Remove the flag and code when the legacy code path is no longer in use.
+
+Method 2 \- Make the new code path opt\-in for Chromium
+
+ * Add new code to Skia, suppressed by a flag.
+ * Leave the old code path in place.
+ * Set the flag in Chromium's 'skia/skia_common.gypi' or
+ 'skia/config/SkUserConfig.h' to enable the new or updated Skia API.
+ * Test the new or updated Skia API within Chromium.
+ * Remove the code suppression \(and code\) when the legacy API is no longer
+ in use.
+
+If your changes will affect Blink layout tests, see detailed instructions about
+how to synchronize the changes between Skia, Blink, and Chromium [here](./blink).
+
diff --git a/site2/docs/dev/chrome/commandbuffer.md b/site2/docs/dev/chrome/commandbuffer.md
new file mode 100644
index 0000000..20c55ef
--- /dev/null
+++ b/site2/docs/dev/chrome/commandbuffer.md
@@ -0,0 +1,28 @@
+
+---
+title: "Chromium Command Buffer"
+linkTitle: "Chromium Command Buffer"
+
+---
+
+
+It is possible to run Skia's correctness tool, dm, and benchmarking tool,
+nanobench, on top of the GL ES interface provided by Chromium's command
+buffer.
+
+The Skia tools are always built with this support. They dynamically load
+the command buffer as a shared library and thus no GYP/GN flags are
+required.
+
+The command buffer standalone shared library is built in a Chromium checkout
+by building the `command_buffer_gles2` target. The command buffer should be
+built with the `is_component_build` in GN set to false. This will produce a .so,
+.dylib, or .dll depending on the target OS. This should be copied alongside
+the dm or nanobench executable built from a Skia repository.
+
+Both tools have a `commandbuffer` config which can be used with the `--config`
+option to the tool and will run the tests or benchmarks using the command buffer
+library. Unit tests in dm always run on all appropriate and available backends
+regardless of the `--config` flag.
+
+
diff --git a/site2/docs/dev/chrome/multi_repo_trybots.md b/site2/docs/dev/chrome/multi_repo_trybots.md
new file mode 100644
index 0000000..68d503b
--- /dev/null
+++ b/site2/docs/dev/chrome/multi_repo_trybots.md
@@ -0,0 +1,91 @@
+
+---
+title: "Multiple repo Chromium trybots"
+linkTitle: "Multiple repo Chromium trybots"
+
+---
+
+
+When a proposed Skia change will require a change in Chromium or Blink it is
+often helpful to locally create the Chromium and Blink changes and test with the
+proposed Skia change. This often happens with Skia API changes and changes
+which affect Blink layout tests. While simple to do locally, this explains how
+to do so on the Chromium trybots.
+
+Skia only changes
+-----------------
+If the Skia patch is already in Gerrit and there are no associated Chromium
+changes, then it is possible to just run the Chromium trybots. This will apply
+the Skia patch and run the bot.
+
+Skia and Chromium changes
+-------------------------
+If the Skia patch is already in Gerrit and there are associated Chromium
+changes, then in the Chromium CL add the following to
+\<chromium>/src/DEPS in the 'hooks' array.
+
+ {
+ 'name': 'fetch_custom_patch',
+ 'pattern': '.',
+ 'action': [ 'git', '-C', 'src/third_party/skia/',
+ 'fetch', 'https://skia.googlesource.com/skia', 'refs/changes/13/10513/13',
+ ],
+ },
+ {
+ 'name': 'apply_custom_patch',
+ 'pattern': '.',
+ 'action': ['git', '-C', 'src/third_party/skia/',
+ '-c', 'user.name=Custom Patch', '-c', 'user.email=custompatch@example.com',
+ 'cherry-pick', 'FETCH_HEAD',
+ ],
+ },
+
+Modify the 'refs/changes/XX/YYYY/ZZ' to the appropriate values (where YYYY is
+the numeric change number, ZZ is the patch set number and XX is the last two
+digits of the numeric change number). This can be seen in the 'Download' link on
+Gerrit.
+
+If this is for a project other than Skia, update the checkout directory and
+fetch source. Note that this can be used multiple times to apply multiple
+issues.
+
+An example of this being used can be seen at
+https://crrev.com/2786433004/#ps1 .
+
+To test locally, run `gclient runhooks` to update the Skia source code.
+Note that if your local skia patch in `third_party/skia` isn't clean (e.g., you
+already applied some patch to it), then `gclient runhooks` won't successfully
+run. In that case, run `git reset --hard` inside `third_party/skia` before
+`gclient runhooks`.
+
+Arbitrary changes
+-----------------
+If the patch is to files where the above is not possible, then it is still
+possible to patch the files manually by adding the following to
+\<chromium>/src/DEPS in the 'hooks' array just before the 'gyp' hook.
+
+ {
+ 'name': 'apply_custom_patch',
+ 'pattern': '.',
+ 'action': ['python2',
+ '-c', 'from distutils.dir_util import copy_tree; copy_tree("src/patch/", "src/");'
+ ],
+ },
+
+Then, copy all 'out of tree' files into \<chromium>/src/patch/, using the same
+directory structure used by Chromium. When `gclient runhooks` is run, the files
+in \<chromium>/src/patch/ will be copied to and overwrite corresponding files in
+\<chromium>/src/. For example, if changing \<skia>/include/core/SkPath.h, place
+a copy of the modified SkPath.h at
+\<chromium>/src/patch/third_party/skia/include/core/SkPath.h.
+
+An example of this being used can be seen at
+https://crrev.com/1866773002/#ps20001 .
+
+
+Try the patch
+-------------
+After committing a \<chromium>/src/DEPS or \<chromium>/src/patch/ change
+locally, `git cl upload` can be used in the usual way. Be sure to add
+`COMMIT=false` to the issue description to avoid accidentally checking it in.
+
diff --git a/site2/docs/dev/chrome/repo.md b/site2/docs/dev/chrome/repo.md
new file mode 100644
index 0000000..46f197c
--- /dev/null
+++ b/site2/docs/dev/chrome/repo.md
@@ -0,0 +1,23 @@
+
+---
+title: "Working in a Chromium repo"
+linkTitle: "Working in a Chromium repo"
+
+---
+
+
+To work on Skia inside a Chromium checkout, run the following:
+
+ cd chromium/src/third_party/skia
+ python2 tools/git-sync-deps
+ bin/gn gen out/Debug
+
+The second command does a minimal "just sync the DEPS" emulation of `gclient
+sync` for Skia into chromium/src/third_party/skia/third_party. After that,
+`ninja -C out/Debug dm` in chromium/src/third_party/skia will get you rolling.
+
+We no longer recommend the .gclient file manipulation to have Chromium DEPS also
+sync Skia's DEPS. Most of those DEPS are for building and testing only;
+Chromium doesn't need any of them, and it can be confusing and problematic if
+they somehow get mixed into the Chromium build.
+