Skip to content

chore: fix autoversion script and update experiments/docs versions #17954

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
May 22, 2025
Merged

chore: fix autoversion script and update experiments/docs versions #17954

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a8a640f
chore: fall back to `gh auth login` for update_experiments.sh script
bpmct May 20, 2025
b4ed9d2
refactor: update experiment parsing script to use ExperimentsSafe ins…
bpmct May 20, 2025
89144e9
docs: add prebuilds experiment
bpmct May 20, 2025
6bc8796
bump version
bpmct May 20, 2025
068a293
fmt (🤞)
bpmct May 20, 2025
38b093d
fmt
bpmct May 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/install/kubernetes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ We support two release channels: mainline and stable - read the
helm install coder coder-v2/coder \
--namespace coder \
--values values.yaml \
--version 2.20.0
--version 2.22.1
```

- **Stable** Coder release:
Expand Down
92 changes: 58 additions & 34 deletions docs/install/releases/feature-stages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,32 +24,37 @@ If you encounter an issue with any Coder feature, please submit a
Early access features are neither feature-complete nor stable. We do not
recommend using early access features in production deployments.

Coder sometimes releases early access features that are available for use, but are disabled by default.
You shouldn't use early access features in production because they might cause performance or stability issues.
Early access features can be mostly feature-complete, but require further internal testing and remain in the early access stage for at least one month.
Coder sometimes releases early access features that are available for use, but
are disabled by default. You shouldn't use early access features in production
because they might cause performance or stability issues. Early access features
can be mostly feature-complete, but require further internal testing and remain
in the early access stage for at least one month.

Coder may make significant changes or revert features to a feature flag at any time.
Coder may make significant changes or revert features to a feature flag at any
time.

If you plan to activate an early access feature, we suggest that you use a
staging deployment.

<details><summary>To enable early access features:</summary>

Use the [Coder CLI](../../install/cli.md) `--experiments` flag to enable early access features:
Use the [Coder CLI](../../install/cli.md) `--experiments` flag to enable early
access features:

- Enable all early access features:

```shell
coder server --experiments=*
```
```shell
coder server --experiments=*
```

- Enable multiple early access features:

```shell
coder server --experiments=feature1,feature2
```
```shell
coder server --experiments=feature1,feature2
```

You can also use the `CODER_EXPERIMENTS` [environment variable](../../admin/setup/index.md).
You can also use the `CODER_EXPERIMENTS`
[environment variable](../../admin/setup/index.md).

You can opt-out of a feature after you've enabled it.

Expand All @@ -60,49 +65,68 @@ You can opt-out of a feature after you've enabled it.
<!-- Code generated by scripts/release/docs_update_experiments.sh. DO NOT EDIT. -->
<!-- BEGIN: available-experimental-features -->

Currently no experimental features are available in the latest mainline or stable release.
| Feature | Description | Available in |
|-----------------------|----------------------------------------------|--------------|
| `workspace-prebuilds` | Enables the new workspace prebuilds feature. | mainline |

<!-- END: available-experimental-features -->

## Beta

- **Stable**: No
- **Production-ready**: Not fully
- **Support**: Documentation, [Discord](https://discord.gg/coder), and [GitHub issues](https://github.com/coder/coder/issues)
- **Support**: Documentation, [Discord](https://discord.gg/coder), and
[GitHub issues](https://github.com/coder/coder/issues)

Beta features are open to the public and are tagged with a `Beta` label.

They’re in active development and subject to minor changes.
They might contain minor bugs, but are generally ready for use.
They’re in active development and subject to minor changes. They might contain
minor bugs, but are generally ready for use.

Beta features are often ready for general availability within two-three releases.
You should test beta features in staging environments.
You can use beta features in production, but should set expectations and inform users that some features may be incomplete.
Beta features are often ready for general availability within two-three
releases. You should test beta features in staging environments. You can use
beta features in production, but should set expectations and inform users that
some features may be incomplete.

We keep documentation about beta features up-to-date with the latest information, including planned features, limitations, and workarounds.
If you encounter an issue, please contact your [Coder account team](https://coder.com/contact), reach out on [Discord](https://discord.gg/coder), or create a [GitHub issues](https://github.com/coder/coder/issues) if there isn't one already.
While we will do our best to provide support with beta features, most issues will be escalated to the product team.
Beta features are not covered within service-level agreements (SLA).
We keep documentation about beta features up-to-date with the latest
information, including planned features, limitations, and workarounds. If you
encounter an issue, please contact your
[Coder account team](https://coder.com/contact), reach out on
[Discord](https://discord.gg/coder), or create a
[GitHub issues](https://github.com/coder/coder/issues) if there isn't one
already. While we will do our best to provide support with beta features, most
issues will be escalated to the product team. Beta features are not covered
within service-level agreements (SLA).

Most beta features are enabled by default.
Beta features are announced through the [Coder Changelog](https://coder.com/changelog), and more information is available in the documentation.
Most beta features are enabled by default. Beta features are announced through
the [Coder Changelog](https://coder.com/changelog), and more information is
available in the documentation.

## General Availability (GA)

- **Stable**: Yes
- **Production-ready**: Yes
- **Support**: Yes, [based on license](https://coder.com/pricing).

All features that are not explicitly tagged as `Early access` or `Beta` are considered generally available (GA).
They have been tested, are stable, and are enabled by default.
All features that are not explicitly tagged as `Early access` or `Beta` are
considered generally available (GA). They have been tested, are stable, and are
enabled by default.

If your Coder license includes an SLA, please consult it for an outline of specific expectations.
If your Coder license includes an SLA, please consult it for an outline of
specific expectations.

For support, consult our knowledgeable and growing community on [Discord](https://discord.gg/coder), or create a [GitHub issue](https://github.com/coder/coder/issues) if one doesn't exist already.
Customers with a valid Coder license, can submit a support request or contact your [account team](https://coder.com/contact).
For support, consult our knowledgeable and growing community on
[Discord](https://discord.gg/coder), or create a
[GitHub issue](https://github.com/coder/coder/issues) if one doesn't exist
already. Customers with a valid Coder license, can submit a support request or
contact your [account team](https://coder.com/contact).

We intend [Coder documentation](../../README.md) to be the [single source of truth](https://en.wikipedia.org/wiki/Single_source_of_truth) and all features should have some form of complete documentation that outlines how to use or implement a feature.
If you discover an error or if you have a suggestion that could improve the documentation, please [submit a GitHub issue](https://github.com/coder/internal/issues/new?title=request%28docs%29%3A+request+title+here&labels=["customer-feedback","docs"]&body=please+enter+your+request+here).
We intend [Coder documentation](../../README.md) to be the
[single source of truth](https://en.wikipedia.org/wiki/Single_source_of_truth)
and all features should have some form of complete documentation that outlines
how to use or implement a feature. If you discover an error or if you have a
suggestion that could improve the documentation, please
[submit a GitHub issue](https://github.com/coder/internal/issues/new?title=request%28docs%29%3A+request+title+here&labels=["customer-feedback","docs"]&body=please+enter+your+request+here).

Some GA features can be disabled for air-gapped deployments.
Consult the feature's documentation or submit a support ticket for assistance.
Some GA features can be disabled for air-gapped deployments. Consult the
feature's documentation or submit a support ticket for assistance.
75 changes: 36 additions & 39 deletions scripts/release/docs_update_experiments.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,27 +12,33 @@ set -euo pipefail
source "$(dirname "${BASH_SOURCE[0]}")/../lib.sh"
cdroot

# Ensure GITHUB_TOKEN is available
if [[ -z "${GITHUB_TOKEN:-}" ]]; then
if GITHUB_TOKEN="$(gh auth token 2>/dev/null)"; then
export GITHUB_TOKEN
else
echo "Error: GitHub token not found. Please run 'gh auth login' to authenticate." >&2
exit 1
fi
fi

if isdarwin; then
dependencies gsed gawk
sed() { gsed "$@"; }
awk() { gawk "$@"; }
fi

# From install.sh
echo_latest_stable_version() {
# https://gist.github.com/lukechilds/a83e1d7127b78fef38c2914c4ececc3c#gistcomment-2758860
# Extract redirect URL to determine latest stable tag
version="$(curl -fsSLI -o /dev/null -w "%{url_effective}" https://github.com/coder/coder/releases/latest)"
version="${version#https://github.com/coder/coder/releases/tag/v}"
echo "v${version}"
}

echo_latest_mainline_version() {
# Fetch the releases from the GitHub API, sort by version number,
# and take the first result. Note that we're sorting by space-
# separated numbers and without utilizing the sort -V flag for the
# best compatibility.
# Use GitHub API to get latest release version, authenticated
echo "v$(
curl -fsSL https://api.github.com/repos/coder/coder/releases |
curl -fsSL -H "Authorization: token ${GITHUB_TOKEN}" https://api.github.com/repos/coder/coder/releases |
awk -F'"' '/"tag_name"/ {print $4}' |
tr -d v |
tr . ' ' |
Expand All @@ -42,7 +48,6 @@ echo_latest_mainline_version() {
)"
}

# For testing or including experiments from `main`.
echo_latest_main_version() {
echo origin/main
}
Expand All @@ -59,33 +64,29 @@ sparse_clone_codersdk() {
}

parse_all_experiments() {
# Go doc doesn't include inline array comments, so this parsing should be
# good enough. We remove all whitespaces so that we can extract a plain
# string that looks like {}, {ExpA}, or {ExpA,ExpB,}.
#
# Example: ExperimentsAll=Experiments{ExperimentNotifications,ExperimentAutoFillParameters,}
go doc -all -C "${dir}" ./codersdk ExperimentsAll |
# Try ExperimentsSafe first, then fall back to ExperimentsAll if needed
experiments_var="ExperimentsSafe"
experiments_output=$(go doc -all -C "${dir}" ./codersdk "${experiments_var}" 2>/dev/null || true)

if [[ -z "${experiments_output}" ]]; then
# Fall back to ExperimentsAll if ExperimentsSafe is not found
experiments_var="ExperimentsAll"
experiments_output=$(go doc -all -C "${dir}" ./codersdk "${experiments_var}" 2>/dev/null || true)

if [[ -z "${experiments_output}" ]]; then
log "Warning: Neither ExperimentsSafe nor ExperimentsAll found in ${dir}"
return
fi
fi

echo "${experiments_output}" |
tr -d $'\n\t ' |
grep -E -o 'ExperimentsAll=Experiments\{[^}]*\}' |
grep -E -o "${experiments_var}=Experiments\{[^}]*\}" |
sed -e 's/.*{\(.*\)}.*/\1/' |
tr ',' '\n'
}

parse_experiments() {
# Extracts the experiment name and description from the Go doc output.
# The output is in the format:
#
# ||Add new experiments here!
# ExperimentExample|example|This isn't used for anything.
# ExperimentAutoFillParameters|auto-fill-parameters|This should not be taken out of experiments until we have redesigned the feature.
# ExperimentMultiOrganization|multi-organization|Requires organization context for interactions, default org is assumed.
# ExperimentCustomRoles|custom-roles|Allows creating runtime custom roles.
# ExperimentNotifications|notifications|Sends notifications via SMTP and webhooks following certain events.
# ExperimentWorkspaceUsage|workspace-usage|Enables the new workspace usage tracking.
# ||ExperimentTest is an experiment with
# ||a preceding multi line comment!?
# ExperimentTest|test|
#
go doc -all -C "${1}" ./codersdk Experiment |
sed \
-e 's/\t\(Experiment[^ ]*\)\ \ *Experiment = "\([^"]*\)"\(.*\/\/ \(.*\)\)\?/\1|\2|\4/' \
Expand All @@ -104,6 +105,11 @@ for channel in mainline stable; do
log "Fetching experiments from ${channel}"

tag=$(echo_latest_"${channel}"_version)
if [[ -z "${tag}" || "${tag}" == "v" ]]; then
echo "Error: Failed to retrieve valid ${channel} version tag. Check your GitHub token or rate limit." >&2
exit 1
fi

dir="$(sparse_clone_codersdk "${workdir}" "${channel}" "${tag}")"

declare -A all_experiments=()
Expand All @@ -115,14 +121,12 @@ for channel in mainline stable; do
done
fi

# Track preceding/multiline comments.
maybe_desc=

while read -r line; do
line=${line//$'\n'/}
readarray -d '|' -t parts <<<"$line"

# Missing var/key, this is a comment or description.
if [[ -z ${parts[0]} ]]; then
maybe_desc+="${parts[2]//$'\n'/ }"
continue
Expand All @@ -133,24 +137,20 @@ for channel in mainline stable; do
desc="${parts[2]}"
desc=${desc//$'\n'/}

# If desc (trailing comment) is empty, use the preceding/multiline comment.
if [[ -z "${desc}" ]]; then
desc="${maybe_desc% }"
fi
maybe_desc=

# Skip experiments not listed in ExperimentsAll.
if [[ ! -v all_experiments[$var] ]]; then
log "Skipping ${var}, not listed in ExperimentsAll"
log "Skipping ${var}, not listed in experiments list"
continue
fi

# Don't overwrite desc, prefer first come, first served (i.e. mainline > stable).
if [[ ! -v experiments[$key] ]]; then
experiments[$key]="$desc"
fi

# Track the release channels where the experiment is available.
experiment_tags[$key]+="${channel}, "
done < <(parse_experiments "${dir}")
done
Expand All @@ -170,14 +170,11 @@ table="$(
done
)"

# Use awk to print everything outside the BEING/END block and insert the
# table in between.
awk \
-v table="${table}" \
'BEGIN{include=1} /BEGIN: available-experimental-features/{print; print table; include=0} /END: available-experimental-features/{include=1} include' \
"${dest}" \
>"${dest}".tmp
mv "${dest}".tmp "${dest}"

# Format the file for a pretty table (target single file for speed).
(cd site && pnpm exec prettier --cache --write ../"${dest}")
Loading