# Docusaurus
Updates the website (/docs) to leverage
[Docusaurus](https://docusaurus.io/) in place of Hugo as its static site
generator.
## Functional changes
### Versioning
The existing Hugo-based site only has a partial versioning story.
The API docs are versioned, but the rest of the content isn't.
This creates a messy story where our hand-written docs likely only
discuss topics related to the current version, and we have no place to
put docs discussing earlier versions.
Or, even worse, we have a mixed bag of documentation for different
versions, creating a very unclear user story.
This prototype includes an end-to-end versioning story, [automated by
Docusaurus](https://docusaurus.io/docs/versioning).
Current (v2) docs live under `docs`.
Old (v1) docs live under `versioned_docs/version-1`.
Most of the documentation has been duplicated between the two versions,
but some minor changes have been made to make the docs better line up
with the corresponding version of the API.
These changes should be reviewed before being merged into main /
deploying the new website.
### Search
This branch includes an offline implementation of search.
An offline solution comes with some downsides (slower build, larger
bundle), and probably isn't what we want long term.
That said, it is much better than what our current website has (no
search whatsoever).
We should come back to this after v1 of our new website.
---------
Co-authored-by: Wayne Ferrao <wayneferrao@microsoft.com>
Whitelist `public`, `beta`, and `legacy.*` as requiring review.
`alpha` changes are still best reviewed, but there is no hard owner requirement to complete PR.
`build-tools` and `server` exclusions can be removed as not broken into
those categories.
GitHub does not create heading IDs in the Releases UI, so our release
note TOC links don't work. This change adds a remarkjs/unist plugin that
inserts HTML anchors into the headings.
Also updates the intro message on the release notes issue to include a
command that can be used to generate the release notes locally.
[AB#14174](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/14174)
---------
Co-authored-by: Alex Villarreal <716334+alexvy86@users.noreply.github.com>
The standard token doesn't have `org:read` permissions, and that scope
can't be added using permissions in the workflow. So instead use a
custom token that has only those permissions.
The first attempt at a release approval workflow didn't work. The
biggest problem is that the workflow can't enumerate team membership if
it's triggered by a `pull_request`, because the token it gets does not
and cannot have those permissions. To work around this, I split the
workflow into two pieces.
The first workflow is triggered by `pull_request` and
`pull_request_review`, and collects a little metadata about the PR which
is uploaded as a build artifact.
The second workflow is triggered by the completion of the first
(`workflow_run`). It downloads the metadata from the earlier workflow
and, if the metadata indicates, checks that the PR is approved by the
right folks. If it isn't, then it writes a failing status check to
GitHub. We can then require that check to pass for release PRs to be
merged.
I also removed the CODEOWNER approval requirements for the workflows
with a follow-up to re-enable them once the workflows are stable. I was
far too optimistic about how much iteration we'd need.
### Why so complicated?
Yeah, this process is not as simple as it should be. Part of the problem
is auth as noted above. Another problem is that there is no way (that I
have found) to trigger a workflow on `pull_request_review` ONLY for PRs
targeting certain branches, so every PR review on _any_ branch will
trigger this workflow! Given that, I tried to keep that workflow
lightweight. If we download the repo and install build-tools on _every
PR review_ that's a ridiculous amount of wasted resources.
Another source of complexity is supporting manual runs using the
`workflow_dispatch` event. This is very useful for testing and in cases
where the triggers don't work as we expect and a PR gets blocked.
However, it means the workflow has to take input from both the previous
workflow (via the uploaded artifacts) and from the `workflow_dispatch`
event that users provide when running the workflow. That amounts to a
bunch of conditional steps.
What we get in exchange for this complexity, though, is a workflow that
runs in seconds in the typical case, and only does the expensive work of
downloading, building, and running build-tools when running against
release branch PRs.
One of the output variables had an empty line in it, which meant the
checks weren't getting triggered since the value wasn't the expected
one. Also, the GitHub Actions token doesn't have org:read permissions,
and those can't be given using the `permissions` block in the workflow,
so I created a new narrowly scoped PAT and added it as a secret.
Adds a new flub command, check:prApproval, which is used to check if a
PR in the repo is approved by a GitHub team or list of users.
This command is then used in a new workflow that runs on release branch
PRs to check that a member of the FluidFramework-ReleaseApprovers team
has approved the PR. We'll then make that a required check for release
branch PRs.
Finally, the CODEOWNERS file is updated to require approval from
FluidFramework-ReleaseApprovers for changes to the workflow itself.
The command can be run locally with a GitHub PAT, which is how I tested.
I also tested against a test branch on my fork. However, none of these
tests is an exact analog to the real Actions environment.
Because of how Actions work, this workflow must be merged to main before
it can be further tested using branches.
[AB#8814](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/8814)
Don't require API reviews for API report changes in `/tools` packages.
Also simplify specification patterns for CODEOWNERS, and...
* Require `fluid-cr-infra` review for API changes in `/build-tools`
packages
* Require `fluid-cr-server` review for API changes in `/server` packages
The release branch warning workflow needs to use the pull_request_target
trigger instead of the pull_request trigger, so it can post to the PR.
This is safe because the PR does not build anything or use content from
the submitted PR. When using pull_request_target the checked-out code is
the base branch, not the PR branch, so there's no access to content from
the PR itself.
Updates the marocchino/sticky-pull-request-comment action to its latest
version, 2.9.0. This upgrade was needed because some options used in
recent workflows are not available in the older version.
I confirmed that the commit 331f8f5b4215f0445d3c07b4967662a32a2d3e31
corresponds to the v2.9.0 tag in the
marocchino/sticky-pull-request-comment repo:
https://github.com/marocchino/sticky-pull-request-comment/releases/tag/v2.9.0
This will be ported to the 2.2 release branch as well.
Adds a GitHub actions workflow to update an issue with the current
release notes every time changesets are added or changed on the main
branch. This will provide a continually updated snapshot of what the
release notes will look like when we release.
I also updated some changeset content to better work with the release
note layout. There will be additional changes made in #22067.
---------
Co-authored-by: Alex Villarreal <716334+alexvy86@users.noreply.github.com>
Co-authored-by: Craig Macomber (Microsoft) <42876482+CraigMacomber@users.noreply.github.com>
Co-authored-by: jzaffiro <110866475+jzaffiro@users.noreply.github.com>
Co-authored-by: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com>
Updating CI to run website validation for changes to any .md files
instead of just changes to the "docs/" directory.
Currently, `markdown-magic` generates some of the content in the docs
using content from sources outside the docs directory including package
READMEs throughout the repo. We want to validate these changes as they
could implicitly break the website content.
The push-tag-create-release workflow was recently updated to support
manual runs using the GitHub UI. However, that change did not update the
step that checked out the release tag, so the release reports are
generated with the wrong data.
It's helpful when preparing for a release to check if any pending PRs
are adding changesets. If the PRs were labeled, doing that query becomes
trivial.
I updated the area labeler to add the
[changeset-present](https://github.com/microsoft/FluidFramework/issues?q=sort%3Aupdated-desc+is%3Aopen+label%3Achangeset-present)
to changes with edits to changesets. This does nothing besides add the
label. Nothing else is automated or changed.
I noticed that changes to the codeowners file itself could be made
without approval, since the file itself was not "owned". I made
@microsoft/fluid-cr-api the owner, but perhaps it should be
@microsoft/fluidframework-admin?
Upgrades pnpm/action-setup to v4 to fix
https://github.com/pnpm/action-setup/issues/135.
I also updated the GH release creation job to support manual runs. That
will allow us to create releases semi-manually from main, so we don't
have to port all the CI fixes to every release branch before we create
the releases.
Our GitHub actions are using some outdated versions of actions. I
updated all of them to the latest without picking up new major versions.
Major upgrades can be done separately.
Command used:
```shell
docker run -it --rm -v "${PWD}:${PWD}" -w "${PWD}" ghcr.io/sethvargo/ratchet:latest update .github/workflows/*.yml
```
Now that the GitHub release process has been working stably for several
months, I've updated the workflow to auto-publish patch releases. This
means that the person doing the release won't need to do anything extra
to get the release published on GitHub.
Applies to patches only; minor and major releases are still left as
drafts.
Updates the dependencies in docs to the latest. Hugo is the exception,
since upgrading it may directly affect fluidframework.com and should be
tested more thoroughly. These updates are reasonably safe, despite being
major version bumps in some cases.
Additionally, this fixes the linkcheck-bin dependency to work properly
on arm64 mac and Linux systems.
## Description
Removes packageVersion.ts files (which are autogenerated) from those
package authors subscribe to when adding an entry for a package's source
tree. This should give less friction to bump PRs in future release
branches.
Co-authored-by: Abram Sanderson <absander@microsoft.com>
As we rollout the new code ownership model we've found that the current
ownership is primarily about source, and not about the package and build
infrastructure, so moving all the existing source based ownership to
only cover the source
---------
Co-authored-by: Tony Murphy <anthonm@microsoft.com>
In order to enable require review from code owners on PR review we will
reset the state of the code owners file. Then it will be the
responsibility of owners to take explicit responsibility for areas of
the codebase they would like to own.
---------
Co-authored-by: Tony Murphy <anthonm@microsoft.com>
## Description
These action are no longer used now that we don't maintain a `next`
branch. They will also stop working correctly once GITHUB_TOKEN
permissions are limited to readonly by default.
---------
Co-authored-by: Abram Sanderson <absander@microsoft.com>
All PRs are being labeled "external-contribution". This is probably
because of https://github.com/srvaroa/labeler/issues/123, which has been
resolved in the latest v1 release. I updated the version of the action
to the latest v1 version.
Joshua Smithrud
Tyler Butler
Jason Hartman
Michael Zhen
Daniel Lehenbauer
Craig Macomber (Microsoft)
Abram Sanderson
Alex Villarreal
Tony Murphy
Taylor Williams