Skip to content

Commit 59dd7ac

Browse files
authored
docs: Move strict option to migration section (#81)
#77 shows that https://github.com/bazel-contrib/bazelrc-preset.bzl/blob/0b4df86a3af7e7ca035139139796dff8e243e115/README.md#L31 can cause some confusion. We should move this down into the migration section to have a simple default. I also fix more indentation of codeblocks to be aligned with the enumeration sections.
1 parent 26c2569 commit 59dd7ac

File tree

1 file changed

+53
-42
lines changed

1 file changed

+53
-42
lines changed

README.md

Lines changed: 53 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -21,16 +21,15 @@ Read [the Bazel bazelrc documentation](https://bazel.build/run/bazelrc).
2121
## Install
2222

2323
1. Add `bazelrc-preset.bzl` to your `MODULE.bazel` file.
24-
2. Call it from a BUILD file, for example in `tools/BUILD`:
24+
2. Call it from a `BUILD` file, for example in `tools/BUILD`:
2525

26-
```starlark
27-
load("@bazelrc-preset.bzl", "bazelrc_preset")
26+
```starlark
27+
load("@bazelrc-preset.bzl", "bazelrc_preset")
2828

29-
bazelrc_preset(
30-
name = "preset",
31-
strict = True, # Enable this to opt-in to flags that are flipped in the upcoming major release
32-
)
33-
```
29+
bazelrc_preset(
30+
name = "preset",
31+
)
32+
```
3433

3534
3. Create the preset by running `bazel run //tools:preset.update`.
3635
Note that you don't need to remember the command.
@@ -40,27 +39,27 @@ A test target `preset.update_test` is also created, which prints the command if
4039
We suggest you add it at the top, so that project-specific flags may override values.
4140
See https://bazel.build/configure/best-practices#bazelrc-file
4241

43-
You can copy this template to get started:
42+
You can copy this template to get started:
4443

45-
```
46-
########################
47-
# Import bazelrc presets
48-
import %workspace%/tools/preset.bazelrc
49-
...
50-
51-
########################
52-
# Project-specific flags
53-
# This is also a place to override settings from the presets
54-
55-
...
56-
57-
########################
58-
# User preferences
59-
# Load any settings & overrides specific to the current user from `user.bazelrc`.
60-
# This file should appear in `.gitignore` so that settings are not shared with team members.
61-
# This should be last statement in this config so the user configuration overrides anything above.
62-
try-import %workspace%/user.bazelrc
63-
```
44+
```
45+
########################
46+
# Import bazelrc presets
47+
import %workspace%/tools/preset.bazelrc
48+
...
49+
50+
########################
51+
# Project-specific flags
52+
# This is also a place to override settings from the presets
53+
54+
...
55+
56+
########################
57+
# User preferences
58+
# Load any settings & overrides specific to the current user from `user.bazelrc`.
59+
# This file should appear in `.gitignore` so that settings are not shared with team members.
60+
# This should be last statement in this config so the user configuration overrides anything above.
61+
try-import %workspace%/user.bazelrc
62+
```
6463

6564
5. Some flags are enabled only under a given config.
6665
For example, many flags apply only when running on CI.
@@ -69,8 +68,20 @@ try-import %workspace%/user.bazelrc
6968
## Migrating to stricter flags
7069

7170
Bazel major releases include flag-flips.
71+
We provide a strict preset that includes all flags that will be flipped in the upcoming major release.
72+
To opt-in to these flags, you can set the `strict` attribute to `True` when calling `bazelrc_preset`.
7273

73-
Bazelisk provides [extra command-line options](https://github.com/bazelbuild/bazelisk?tab=readme-ov-file#other-features) to migrate to stricter flags. A common migration pattern is:
74+
```starlark
75+
load("@bazelrc-preset.bzl", "bazelrc_preset")
76+
77+
bazelrc_preset(
78+
name = "preset",
79+
strict = True, # Enable this to opt-in to flags that are flipped in the upcoming major release
80+
)
81+
```
82+
83+
Bazelisk provides [extra command-line options](https://github.com/bazelbuild/bazelisk?tab=readme-ov-file#other-features) to migrate to stricter flags.
84+
A common migration pattern is:
7485

7586
1. Run `bazelisk --migrate build --nobuild //...` to try upgrading new strict flags.
7687
2. For flags that don't work, either
@@ -85,23 +96,23 @@ If your project defines specific flags that users should set, you can define the
8596
1. Define your own flags using the same data structure as [`flags.bzl`](flags.bzl) or [`tests/extra_test_presets.bzl`](tests/extra_test_presets.bzl).
8697
2. Add a `bazelrc_preset_test` to make sure your presets format is correct.
8798

88-
```starlark
89-
bazelrc_preset_test(
90-
name = "test_project_preset",
91-
extra_presets = CUSTOM_PROJECT_PRESETS,
92-
)
93-
```
99+
```starlark
100+
bazelrc_preset_test(
101+
name = "test_project_preset",
102+
extra_presets = CUSTOM_PROJECT_PRESETS,
103+
)
104+
```
94105

95106
3. Any user of your project can now consume your presets and add them to their presets
96107

97-
```starlark
98-
load("@my_project//:flags.bzl", "CUSTOM_PROJECT_PRESETS")
108+
```starlark
109+
load("@my_project//:flags.bzl", "CUSTOM_PROJECT_PRESETS")
99110

100-
bazelrc_preset(
101-
name = "preset",
102-
extra_presets = CUSTOM_PROJECT_PRESETS
103-
)
104-
```
111+
bazelrc_preset(
112+
name = "preset",
113+
extra_presets = CUSTOM_PROJECT_PRESETS
114+
)
115+
```
105116

106117
## References and Credits
107118

0 commit comments

Comments
 (0)