# Objective
- The [developer docs](https://dev-docs.bevyengine.org) are primarily
used by developers, who often deal with internal and private functions.
- @mweatherley suggested [on
Discord](https://discord.com/channels/691052431525675048/743559241461399582/1273658470134186112)
that CI passes `--document-private-items` to the dev-docs, so
contributors can easily browse these internal details.
## Solution
- Add `--document-private-items` to the CI job that builds the dev-docs.
## Testing
- It should run in CI and generate documentation for private code.
## Drawbacks
- Users that track the main branch may use the dev-docs instead of
<https://docs.rs/bevy>, which may now show a lot of unwanted internal
details.
- Searching may be slower / bloated with internal details.
# Objective
This PR is a follow-up to #14703. I forgot to also add the flags from
`package.metadata.docs.rs` to the docs build.
## Solution
As [discussed on
Discord](https://discord.com/channels/691052431525675048/1272629407659589663/1272643734260940940),
I added the missing flags to `docs.yml`.
I also updated `rustc-args` to properly make use of the array (I think
the value has to be either a space-separated string *or* an array of
strings but not an array of space-separated strings 😆)
# Objective
- In #12965 I broke CI (sorry!)
- The command was tested locally, but somehow the yaml formatting messed
it up
- I hate yaml
## Solution
- It should now use the correct formatting
- I hope
- I wish there was a straightforward way to test github actions locally
# Objective
- Fix issue #2611
## Solution
- Add `--generate-link-to-definition` to all the `rustdoc-args` arrays
in the `Cargo.toml`s (for docs.rs)
- Add `--generate-link-to-definition` to the `RUSTDOCFLAGS` environment
variable in the docs workflow (for dev-docs.bevyengine.org)
- Document all the workspace crates in the docs workflow (needed because
otherwise only the source code of the `bevy` package will be included,
making the argument useless)
- I think this also fixes#3662, since it fixes the bug on
dev-docs.bevyengine.org, while on docs.rs it has been fixed for a while
on their side.
---
## Changelog
- The source code viewer on docs.rs now includes links to the
definitions.
# Objective
The robots.txt file for the [dev docs](https://dev-docs.bevyengine.org)
looks like this `User-Agent: *\nDisallow: /`
It should look like this
```
User-Agent: *
Disallow: /
```
## Solution
Use
[`ANSI-C`](https://www.gnu.org/software/bash/manual/bash.html#ANSI_002dC-Quoting)
quoting to properly handle the `\n`
## Testing
- [x] Run the fixed echo command in local terminal.
- [ ] Wait for the dev doces to deploy and observe if the mistake has
been fixed
# Objective
- Some developers enable Github Actions for their fork and commit
directly to main. This triggers the `docs.yml` action, which attempts to
deploy the documentation even if Github Pages is not enabled. (It also
creates a `CNAME` file specific to Bevy and should not be used in forks,
even for testing.)
- For an example, see [this
run](https://github.com/tychedelia/bevy/actions/runs/8978912060/job/24660082729).
## Solution
- Only attempt to deploy docs when running from the main Bevy
repository.
- This does not affect us checking `cargo doc` on pull requests, since
that it done in `ci.yml`.
## Testing
It's difficult to test this, but you'd probably:
1. Fork Bevy
2. Cherry pick this PR's commits onto the main branch of your fork.
3. Push another commit to the main branch, triggering Github Actions.
4. Check the Github Actions job summary to ensure that the
`build-and-deploy` job is skipped.
# Objective
- Some CI jobs specifically use `macos-14`, as compared to the default
`macos-latest`.
- `macos-latest` is equivalent to `macos-12`, but may be updated in the
future.
- The CI job that tests on the minimum supported Rust version (MSRV)
uses environmental variables to save the toolchain version.
- This specific usage is what step outputs were designed for.
- Both do the same thing, but step outputs can be checked by the [Github
Actions VSCode
Extension](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-github-actions).
- Some workflows have a `NIGHTLY_TOOLCHAIN` variable that let us pin the
nightly version, in case a new release breaks CI.
## Solution
- Document why certain actions required `macos-14`.
- Switch MSRV step to use step outputs.
- Add a small comment documenting the purpose of the `NIGHTLY_TOOLCHAIN`
environmental variable.
# Objective
- There are several occurrences where different actions install alsa,
udev, and various other libraries for Linux.
- This is repetitive and can be an issue if the dependencies required by
Bevy ever change.
## Solution
- Create a custom action for installing Linux dependencies.
- It can be used by adding `- uses:
./.github/actions/install-linux-deps`.
- It supports configuring which libraries are installed using the `with`
property.
- It does nothing if not run on Linux, so workflows don't need to worry
about adding `if: ${{ runner.os == 'linux' }}`.
## Discussion
- The only instance where this action is not used cleanly is for the
`run-examples-linux-vulkan` verification job. I need to investigate
further the flags and dependencies that it installs.
# Objective
When working on PRs, I'll often find that one of the early CI checks
fails, and work on fixing the result, but when I push the earlier
commits are still being processed by the CI. This would mean that if a
new commit is pushed while another CI process is already running on that
branch, the first set of jobs will be cancelled - reducing wasted
resources and wait time for CI on the latest commits.
## Solution
The solution is simply adding Github's concurrency groups to every
relevant workflow.
# Objective
- Try to fix deploying docs in CI
- Alternative to https://github.com/bevyengine/bevy/pull/11502
## Solution
- The only issue I could find is the lock file with invalid permissions,
try to remove it
- upload action was doing permissions cleanup in v1, that was removed in
v2. we're now using v3
# Objective
- `actions/upload-pages-artifact` and `actions/deploy-pages` are
outdated.
- Alternative to #11253 and #11252.
## Solution
- Bump the version of both actions.
---
There appear to be no user-facing changes. They just both need to be
updated together. (The `actions: read` permission was a bug that was
fixed later.)
Supersedes #10888.
# Objective
Closes#10821
## Solution
- Replaced
[JamesIves/github-pages-deploy-action](https://github.com/JamesIves/github-pages-deploy-action)
with
[actions/upload-pages-artifact](https://github.com/actions/upload-pages-artifact)
and [actions/deploy-pages](https://github.com/actions/deploy-pages).
## Notes
- I made this workflow possible to run through dispatch
(`workflow_dispatch`), in case something goes wrong.
- I restricted the permissions to just the things Github Pages needs.
- I made it so that only one deployments can happen at a time, the other
deployment requests will be queued up and the latest one will be run.
Bumps [JamesIves/github-pages-deploy-action](https://github.com/JamesIves/github-pages-deploy-action) from 4.1.7 to 4.3.0.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a href="https://github.com/JamesIves/github-pages-deploy-action/releases">JamesIves/github-pages-deploy-action's releases</a>.</em></p>
<blockquote>
<h2>v4.3.0</h2>
<h2>Changes</h2>
<ul>
<li>Implements a new option available behind a flag, <code>force</code>. If set to <code>false</code> the action will no longer force push, instead attempting 3 times to resolve rejected commits when making parallel/subsequent deployments. In a future version <code>false</code> will be set as the default. Massive thanks to <a href="https://github.com/rossjrw"><code>@rossjrw</code></a> for this feature addition.</li>
<li>Modified the Node version which the action is developed/tested against from <code>14</code> to <code>16</code>.</li>
</ul>
<h2>Minor Changes</h2>
<ul>
<li>Third-party dependency updates.</li>
<li>Test coverage improvements.</li>
</ul>
<h2>v4.2.5</h2>
<h2>Minor Changes</h2>
<ul>
<li>Corrects an issue in the publishing pipeline that was causing workflow failures.</li>
</ul>
<h2>v4.2.4</h2>
<h2>Minor Changes</h2>
<ul>
<li>Modified how workflow notices get displayed. (<a href="https://github-redirect.dependabot.com/JamesIves/github-pages-deploy-action/issues/1033">#1033</a> Thanks to <a href="https://github.com/hemberger"><code>@hemberger</code></a>)</li>
<li>Dependency upgrades.</li>
</ul>
<h2>v4.2.3</h2>
<h2>Minor Changes</h2>
<ul>
<li>Improved action logging. This is part 1 or 2 updates that will make the logs easier to traverse. Warnings and notices are now provided so you don't need to expand the logs to get the termination message.</li>
<li>Dependency bumps across the board.</li>
</ul>
<h2>v4.2.2</h2>
<h2>Minor Changes</h2>
<ul>
<li>Introduces major version tags. You can now point your workflow to <code>JamesIves/github-pages-deploy-action@v4</code> if you'd like to always have the most cutting edge changes outside of using the release branch directly.</li>
<li>The version tags for this project now include a <code>v</code> to be consistent with other officially provided actions by GitHub. You can use <code>JamesIves/github-pages-deploy-action@v4.2.2</code> for instance. Dependabot should pick up this change automatically.</li>
</ul>
<h2>4.2.1</h2>
<h2>Minor Changes</h2>
<ul>
<li>Resolves an issue where the operating system warning was showing incorrectly.</li>
</ul>
<h2>4.2.0</h2>
<h1>Happy New Year 2022!</h1>
<p><img src="https://media.giphy.com/media/pYhFb0kn2GhQQ/giphy.gif" alt="London" /></p>
<h2>Minor Changes</h2>
<ul>
<li>Implements a warning if you're using an unsupported operating system. This will occur if the workflow runs within MacOS or Windows. The workflow will not be cancelled.</li>
<li>The action is now case insensitive, allowing you to make casing changes to files so long as you commit them using the <code>git mv</code> command prior to the workflow running. (<a href="https://github-redirect.dependabot.com/JamesIves/github-pages-deploy-action/issues/895">#895</a>)</li>
<li>Fixes an issue that was causing <code>single-commit</code> to fail when using <code>repository-name</code> if the branch name was equal from the origin to destination. (<a href="https://github-redirect.dependabot.com/JamesIves/github-pages-deploy-action/issues/665">#665</a>)</li>
<li>Enabled Dependabot updates for the GitHub Actions that are used as part of the projects integration tests.</li>
</ul>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a href="360c8e75d0"><code>360c8e7</code></a> Merge branch 'dev' into releases/v4</li>
<li><a href="6ae2891783"><code>6ae2891</code></a> Update integration.yml</li>
<li><a href="e6c302f297"><code>e6c302f</code></a> Update README.md</li>
<li><a href="cf0ab8fab5"><code>cf0ab8f</code></a> Deploy Production Code for Commit 7598e9b3fc39a35565f529abe095d4dfe75d52e4 🚀</li>
<li><a href="7598e9b3fc"><code>7598e9b</code></a> Merge branch 'dev' into releases/v4</li>
<li><a href="36e9415933"><code>36e9415</code></a> Improe coverage</li>
<li><a href="e71f256f1c"><code>e71f256</code></a> Bump prettier from 2.6.1 to 2.6.2 (<a href="https://github-redirect.dependabot.com/JamesIves/github-pages-deploy-action/issues/1068">#1068</a>)</li>
<li><a href="95f8a2cd05"><code>95f8a2c</code></a> Resolve simultaneous deployments with rebase (<a href="https://github-redirect.dependabot.com/JamesIves/github-pages-deploy-action/issues/1054">#1054</a>)</li>
<li><a href="cd846deedd"><code>cd846de</code></a> Bump <code>@actions/github</code> from 5.0.0 to 5.0.1 (<a href="https://github-redirect.dependabot.com/JamesIves/github-pages-deploy-action/issues/1067">#1067</a>)</li>
<li><a href="7117b56a56"><code>7117b56</code></a> Bump prettier from 2.6.0 to 2.6.1 (<a href="https://github-redirect.dependabot.com/JamesIves/github-pages-deploy-action/issues/1065">#1065</a>)</li>
<li>Additional commits viewable in <a href="https://github.com/JamesIves/github-pages-deploy-action/compare/4.1.7...v4.3.0">compare view</a></li>
</ul>
</details>
<br />
[](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)
Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
- `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
</details>
# Objective
Partially address #407 by setting up automated deployments of `bevy`'s API reference to GitHub Pages.
## Solution
Set up a GitHub Actions workflow that builds the docs on every push to `main` and pushes a new commit to a `gh-pages` (or `docs` branch).
A few smaller additions to better address #407:
- A top level redirect was added to take "docs.bevyengine.org" directly to the `bevy` crate docs.
- A GitHub Pages CNAME file for supporting a publicly viewable domain instead of `github.io`
- A robots.txt file is added to disable all search engine crawlers that respect it from crawling it (avoid having conflicting Google search results)
- A .nojekyl file to speed up deployments since there is no Jekyll templating in the output.
This may require configuration of the `GITHUB_TOKEN` of the CI to successfully run this.
## Followup
For this to completely resolve#407, a subdomain of https://bevyengine.org/ needs to be set up to point to the CNAME location. This is initially set to "dev-docs.bevyengine.org".
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
