diff --git a/contribute/docs-contribution-workflow.mdx b/contribute/docs-contribution-workflow.mdx new file mode 100644 index 00000000..1380aca2 --- /dev/null +++ b/contribute/docs-contribution-workflow.mdx @@ -0,0 +1,220 @@ +--- +title: 'Docs contribution workflow' +--- + +This page guides you through contributing to the Bazel +documentation, from a one-line typo fix to adding a new page. For style +guidance, see the [Bazel docs style guide](/contribute/docs-style-guide). + +## Bazel docs structure {#structure} + +Bazel documentation lives in two repositories: + +| Repository | What it contains | +|---|---| +| [`bazelbuild/bazel`](https://github.com/bazelbuild/bazel) | All doc content (`docs/` folder). **This is where you make changes.** | +| [`bazel-contrib/bazel-docs`](https://github.com/bazel-contrib/bazel-docs) | The hosting pipeline. Syncs from `bazelbuild/bazel` and deploys to [preview.bazel.build](https://preview.bazel.build). | + +Doc files are in [MDX format](https://mdxjs.com/), which is Markdown with a YAML +frontmatter block at the top. Every page must start with: + +``` +--- +title: 'Your Page Title' +--- +``` + +## Prerequisites {#prerequisites} + +Before you start, you need: + +- A [GitHub account](https://github.com) +- A fork of [`bazelbuild/bazel`](https://github.com/bazelbuild/bazel) +- [Git](https://git-scm.com/) +- The [Mintlify CLI](https://www.mintlify.com/docs/cli/install) for local preview. + +## Type 1: Quick fix {#quick-fix} + +For small isolated changes, such as a typo, broken link, phrasing tweaks, you can edit directly in the GitHub web UI without +cloning anything. + +1. Find the file in + [`bazelbuild/bazel/docs/`](https://github.com/bazelbuild/bazel/tree/master/docs) + on GitHub. +2. To edit the file, click the **pencil icon** in the top-right corner. +3. Make your edit. +4. Click **Commit changes...**, provide a commit message, and click **Propose changes"**. +5. GitHub prompts you to open a pull request. Set the base branch to + **`master`** and click **Create pull request** it. + +## Type 2: Updating existing content {#updating-content} + +Use this workflow for anything larger than a typo, such as rewording a section, +correcting outdated information, or adding a paragraph to an existing page. + +### Set up locally + +Fork [`bazelbuild/bazel`](https://github.com/bazelbuild/bazel) on GitHub first, then clone the repo and add the upstream remote: + +```bash +git clone https://github.com/YOUR_USERNAME/bazel.git +cd bazel +git remote add upstream https://github.com/bazelbuild/bazel.git +``` + +### Make and preview your changes + +Check out a new branch off of `master`. + +```bash +git fetch upstream +git checkout -b my-doc-fix upstream/master +``` + +Edit the file in `docs/`, for example, `docs/concepts/labels.mdx`. + +To preview locally, you need a local copy of `bazel-contrib/bazel-docs`: + +```bash +# One-time setup +git clone https://github.com/bazel-contrib/bazel-docs.git +cd bazel-docs +``` + +Copy your changed file(s) into the local `bazel-docs` mirror to preview them: + +```bash +cp ~/path/to/bazel/docs/concepts/labels.mdx concepts/labels.mdx + +# Start the local dev server +mintlify dev +``` + +Open [http://localhost:3000](http://localhost:3000) to render your changes. + +### Commit and open a PR + +Add, commit, and push your changes: +```bash +git add --all # stage all changes +git commit -m "docs: your commit msg here" +git push origin my-doc-fix # push to GitHub +``` + +Open a pull request on GitHub from your fork to **`bazelbuild/bazel` master**. + +## Type 3: Adding a new section to an existing page {#new-section} + +Follow the same workflow as Type 2. A few things to keep in mind: + +**Add a heading anchor ID.** Every heading should have an explicit `{#id}` so +URLs to that section stay stable even if the heading text changes: + +```md +## My new section {#my-new-section} +``` + +**Use sentence case for headings.** Write "Getting started" not +"Getting Started". + +**Keep the heading hierarchy consistent.** Pages use H2 (`##`) for top-level +sections and H3 (`###`) for subsections. Don't skip levels. + +**Update the page if there's a table of contents or "On this page" intro.** +Some pages have an introductory list of topics — add your section there too. + +## Type 4: Adding a new page {#new-page} + +1. Create the MDX file in the appropriate `docs/` subdirectory. + Every file must start with frontmatter: + + ``` + --- + title: 'Your Page Title' + --- + ``` + +2. Add your page to the navigation in the + `docs.json` file in `bazel-contrib/bazel-docs`. Open an issue or ask a + maintainer to add your page to the nav — you don't need to do this yourself + for an initial PR. + +3. Follow the same branch, commit, and PR steps as Type 2. + +## MDX basics for doc contributors {#mdx-basics} + +MDX is mostly standard Markdown with a few differences. + +### Self-closing HTML tags {#self-closing-tags} + +JSX requires void elements to be self-closing. Use `` and +`
`, not `` or `
`. + +### Links {#links} + +Use root-relative paths for internal links. Don't include the `.mdx` extension in the links: + +```md +[labels](/concepts/labels) +[style guide](/contribute/docs-style-guide) +``` + +### Code blocks {#code-blocks} + +Always specify a language for syntax highlighting: + +````md +```bash +bazel build //my/example:app +``` +```` + +Common languages used in Bazel docs: `bash`, `python`, `starlark`, `json`, +`posix-terminal`. + +### Images {#images} + +Place images in the `images/` subdirectory alongside your MDX file and +reference them with a root-relative path: + +```md +![Alt text](/contribute/images/my-diagram.png) +``` + +Use self-closing syntax: Markdown image syntax does not require the trailing `/>`, +but `` tags must self-close when you use them directly: + +```md +Alt text +``` + +### Notes and callouts {#callouts} + +Mintlify supports callout components. Use them for important warnings or tips: + +```md + +This is a note. + + + +This is a warning. + +``` + +## What to expect after submitting {#after-submitting} + +- The Google CLA bot checks that you've signed the + [Contributor License Agreement](https://cla.developers.google.com/). You + only need to do this once. +- CI runs a docs validation check. +- A maintainer reviews your PR and might make requests for edits. Response times vary. +- Once approved, your changes are merged to `master` and appear on the + live site after the next sync. + +## Getting help {#getting-help} + +- File an issue in [`bazelbuild/bazel`](https://github.com/bazelbuild/bazel/issues) + with the label `type: documentation`. +- For questions about the docs platform, open an + issue in [`bazel-contrib/bazel-docs`](https://github.com/bazel-contrib/bazel-docs/issues). diff --git a/reference/command-line-reference.mdx b/reference/command-line-reference.mdx index 74feb043..6f51089e 100644 --- a/reference/command-line-reference.mdx +++ b/reference/command-line-reference.mdx @@ -1804,14 +1804,14 @@ Miscellaneous options, not otherwise categorized.: `--[no]show_timestamps` default: "false" : Include timestamps in messages -`--tls_certificate=` default: see description -: Specify a path to a TLS certificate that is trusted to sign server certificates. An empty value resets the flag to its default. +`--tls_certificate=` default: see description +: Specify a path to a TLS certificate that is trusted to sign server certificates. -`--tls_client_certificate=` default: see description -: Specify the TLS client certificate to use; you also need to provide a client key to enable client authentication. An empty value resets the flag to its default. +`--tls_client_certificate=` default: see description +: Specify the TLS client certificate to use; you also need to provide a client key to enable client authentication. -`--tls_client_key=` default: see description -: Specify the TLS client key to use; you also need to provide a client certificate to enable client authentication. An empty value resets the flag to its default. +`--tls_client_key=` default: see description +: Specify the TLS client key to use; you also need to provide a client certificate to enable client authentication. `--ui_actions_shown=` default: "8" : Number of concurrent actions shown in the detailed progress bar; each action is shown on a separate line. The progress bar always shows at least one one, all numbers less than 1 are mapped to 1. @@ -4587,12 +4587,6 @@ Remote caching and execution options: `--[no]remote_verify_downloads` default: "true" : If set to true, Bazel will compute the hash sum of all remote downloads and discard the remotely cached values if they don't match the expected value. -`--[no]rewind_lost_inputs` default: "false" -: Whether to use action rewinding to recover from lost inputs. - - Tags: - [`execution`](#effect_tag_EXECUTION) - Miscellaneous options, not otherwise categorized.: `--[no]allow_analysis_cache_discard` default: "true" diff --git a/release/index.mdx b/release/index.mdx index 6fb24547..822c08f5 100644 --- a/release/index.mdx +++ b/release/index.mdx @@ -15,7 +15,7 @@ information about Bazel's release model. | ----------- | ------------- | -------------- | -------------- | | Bazel 10 | Rolling| [Check rolling release page](/release/rolling) | N/A | | Bazel 9 | Active| [9.1.0](https://github.com/bazelbuild/bazel/releases/tag/9.1.0) | Dec 2028 | -| Bazel 8 | Maintenance| [8.7.0](https://github.com/bazelbuild/bazel/releases/tag/8.7.0) | Dec 2027 | +| Bazel 8 | Maintenance| [8.6.0](https://github.com/bazelbuild/bazel/releases/tag/8.6.0) | Dec 2027 | | Bazel 7 | Maintenance| [7.7.1](https://github.com/bazelbuild/bazel/releases/tag/7.7.1) | Dec 2026 | | Bazel 6 | Deprecated | [6.6.0](https://github.com/bazelbuild/bazel/releases/tag/6.6.0) | Dec 2025 | | Bazel 5 | Deprecated | [5.4.1](https://github.com/bazelbuild/bazel/releases/tag/5.4.1) | Jan 2025 | diff --git a/rules/lib/builtins/ToolchainContext.mdx b/rules/lib/builtins/ToolchainContext.mdx index 24326f9a..d792e7e6 100644 --- a/rules/lib/builtins/ToolchainContext.mdx +++ b/rules/lib/builtins/ToolchainContext.mdx @@ -2,16 +2,4 @@ title: 'ToolchainContext' --- -Holds toolchains available for a particular exec group. Toolchain targets are accessed by indexing with the toolchain type, as in `ctx.toolchains["//pkg:my_toolchain_type"]`. If the toolchain was optional and no toolchain was resolved, this will return `None`. Accessing toolchains of an aspect or rule via `ctx.toolchains` returns the indexed toolchain as a `ToolchainInfo` provider. While when using aspects, `ToolchainContext` is also used to hold the toolchains of the base target. It can be accessed by `ctx.rule.toolchains["//pkg:my_toolchain_type"]` and it returns the list of providers resulted from applying the aspects on these toolchain targets. - -## Members - -* [toolchain_types](#toolchain_types) - -## toolchain_types - -``` -sequence ToolchainContext.toolchain_types() -``` - -Returns the resolved toolchain type labels. \ No newline at end of file +Holds toolchains available for a particular exec group. Toolchain targets are accessed by indexing with the toolchain type, as in `ctx.toolchains["//pkg:my_toolchain_type"]`. If the toolchain was optional and no toolchain was resolved, this will return `None`. Accessing toolchains of an aspect or rule via `ctx.toolchains` returns the indexed toolchain as a `ToolchainInfo` provider. While when using aspects, `ToolchainContext` is also used to hold the toolchains of the base target. It can be accessed by `ctx.rule.toolchains["//pkg:my_toolchain_type"]` and it returns the list of providers resulted from applying the aspects on these toolchain targets. \ No newline at end of file diff --git a/rules/lib/toplevel/cc_common.mdx b/rules/lib/toplevel/cc_common.mdx index 6ed7e5fc..9b48c9a6 100644 --- a/rules/lib/toplevel/cc_common.mdx +++ b/rules/lib/toplevel/cc_common.mdx @@ -57,7 +57,7 @@ The key used to retrieve the provider that contains information about the C++ to ## compile ``` -tuple cc_common.compile(*, actions, feature_configuration, cc_toolchain, srcs=[], public_hdrs=[], private_hdrs=[], includes=[], local_includes=[], quote_includes=[], system_includes=[], framework_includes=[], defines=[], local_defines=[], include_prefix='', strip_include_prefix='', user_compile_flags=[], conly_flags=[], cxx_flags=[], compilation_contexts=[], name, disallow_pic_outputs=False, disallow_nopic_outputs=False, additional_inputs=[], module_interfaces=unbound) +tuple cc_common.compile(*, actions, feature_configuration, cc_toolchain, srcs=[], public_hdrs=[], private_hdrs=[], includes=[], quote_includes=[], system_includes=[], framework_includes=[], defines=[], local_defines=[], include_prefix='', strip_include_prefix='', user_compile_flags=[], conly_flags=[], cxx_flags=[], compilation_contexts=[], name, disallow_pic_outputs=False, disallow_nopic_outputs=False, additional_inputs=[], module_interfaces=unbound) ``` Should be used for C++ compilation. Returns tuple of (`CompilationContext`, `CcCompilationOutputs`). @@ -73,7 +73,6 @@ Should be used for C++ compilation. Returns tuple of (`CompilationContext`, `CcC | `public_hdrs` | [sequence](../core/list); default is `[]` List of headers needed for compilation of srcs and may be included by dependent rules transitively. | | `private_hdrs` | [sequence](../core/list); default is `[]` List of headers needed for compilation of srcs and NOT to be included by dependent rules. | | `includes` | [sequence](../core/list); or [depset](../builtins/depset); default is `[]` Search paths for header files referenced both by angle bracket and quotes. Usually passed with -I. Propagated to dependents transitively. | -| `local_includes` | [sequence](../core/list); or [depset](../builtins/depset); default is `[]` Search paths for header files referenced by angle brackets and quotes. Usually passed with -I. Not propagated to dependents transitively. | | `quote_includes` | [sequence](../core/list); default is `[]` Search paths for header files referenced by quotes, e.g. #include "foo/bar/header.h". They can be either relative to the exec root or absolute. Usually passed with -iquote. Propagated to dependents transitively. | | `system_includes` | [sequence](../core/list); default is `[]` Search paths for header files referenced by angle brackets, e.g. #include <foo/bar/header.h>. They can be either relative to the exec root or absolute. Usually passed with -isystem. Propagated to dependents transitively. | | `framework_includes` | [sequence](../core/list); default is `[]` Search paths for header files from Apple frameworks. They can be either relative to the exec root or absolute. Usually passed with -F. Propagated to dependents transitively. | diff --git a/upstream b/upstream index 677af8f1..7b7d0a31 160000 --- a/upstream +++ b/upstream @@ -1 +1 @@ -Subproject commit 677af8f1a098eb9773cc3cfc38d384ade87bee41 +Subproject commit 7b7d0a31f79a4a9d0fb6dbc1a68c40fb254014d1