elastic / elastic/oblt-cli-buildkite-plugin

[oblt-aw][autodoc] Documentation drift: incorrect defaults, broken release link, and missing behavior docs

Open
#150 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
PowerShell
Stars
0
Forks
2
Avg merge
1d 21h
Merged PRs (30d)
7

Description

cc `@elastic/observablt-ci`

Recent documentation audit found concrete drift and coverage gaps that can mislead plugin users and contributors.

## Changes Requiring Documentation Updates

### 1. README default `version` value is out of date

**What changed / evidence:**
- `README.md:15` documents default `version` as `8.0.4`.
- `.default-oblt-cli-version:1` is `8.0.21`.
- `hooks/pre-command:11` confirms runtime fallback uses `.default-oblt-cli-version`.

**Documentation impact:** `README.md` properties table currently describes an incorrect default.

### 2. Release guide links to a non-existent workflow file

**What changed / evidence:**
- `docs/RELEASE.md:30` links to `../.github/workflows/bump-readme=version.yml`.
- Actual file is `.github/workflows/bump-readme-version.yml`.

**Documentation impact:** release instructions contain a broken cross-reference.

### 3. Plugin schema description for `version` conflicts with behavior

**What changed / evidence:**
- `plugin.yml:16` says `version` is "The version of the plugin to use".
- `README.md:15` and runtime behavior (`hooks/pre-command:24-26`) show this value selects the **oblt-cli** version.

**Documentation impact:** public plugin configuration docs are inconsistent and can confuse users.

### 4. `command: credentials` is documented as supported, but PowerShell path does not implement it

**What changed / evidence:**
- `README.md:19,35-58` documents `command: credentials` as supported behavior.
- `hooks/pre-command:30-50` implements credentials flow in Bash.
- `hooks/pre-command.ps1:1-27` performs setup only; no `credentials` handling exists.

**Documentation impact:** README should document platform support limitations (or explicit status) for `command: credentials`.

### 5. Missing documentation for global git identity side effects

**What changed / evidence:**
- `hooks/pre-command:21-22` and `hooks/pre-command.ps1:22-23` set global git `user.name` and `user.email`, with `GIT_USER`/`GIT_EMAIL` overrides (`hooks/pre-command.ps1:19-20`).
- No README section explains this behavior.

**Documentation impact:** users on shared/reused agents may be affected by undocumented global git config mutation.

## Suggested Actions

- [ ] Update `README.md` property table so `version` default matches `.default-oblt-cli-version` (or state that file is authoritative).
- [ ] Fix `docs/RELEASE.md` workflow link to `../.github/workflows/bump-readme-version.yml`.
- [ ] Update `plugin.yml` `version` description to clarify it refers to the oblt-cli version.
- [ ] Add a platform support note/matrix for `command: credentials` (Bash implemented; clarify PowerShell status).
- [ ] Add a README note describing git global config side effects and `GIT_USER`/`GIT_EMAIL` overrides.

---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Observability Agentic Workflow — Schedule](https://github.com/elastic/oblt-cli-buildkite-plugin/actions/runs/34444278900)

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
> - [x] expires on Sep 17, 2026, 6:23 AM UTC

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the cited sections in README.md, docs/RELEASE.md, and plugin.yml, then compare them with .default-oblt-cli-version and the Bash and PowerShell pre-command hooks. Done means the default and schema wording are accurate, the release link works, and the README documents credentials platform support plus global Git identity side effects and overrides.

Written by the indexing model from the issue text.

Assessment

Tech stack
bash, git, powershell
Domain
devops, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.