Documentation links created by charmcraft are invalid
Metadata
Current evaluation
Charmcraft CLI help text generates invalid documentation links using full version numbers (e.g., 4.4.1) instead of stable or major version, causing 404 errors.
Suggested action: needs triage
Reason: This is a valid bug with clear reproduction steps and a clear root cause in charmcraft/application/main.py line 48 where docs_url uses {version} placeholder that resolves to the full version string. No maintainer has triaged or acknowledged the issue yet (0 comments, no labels). The fix likely involves using 'stable' or the major version instead of the full version string, as other links in the codebase already use 'stable'.
Impact:
60
Quick Win:
42.0
Staleness:
5
Complexity:
30
Confidence:
80
Support Request:
0
Issue body
### Check existing issues
- [x] I've verified that this bug isn't described by any existing issues.
### Bug description
The documentation links provided by Charmcraft, such as when doing `charmcraft -h` or `charmcraft login -h`, point to an invalid page. The link is built with the full version of Charmcraft CLI, such as `4.4.1`, instead of `4` or `latest`, meaning the links point to nonexistent pages.
### Steps to reproduce
1. Run any command that would generate a documentation link, for example, `charmcraft -h` or `charmcraft login -h`.
2. Try to follow the link presented without modification
3. Observe 404!
### Environment
charmcraft 4.4.1
### charmcraft.yaml
```yaml
If the issue is specific to a project, share its `charmcraft.yaml`. This field automatically renders as YAML, so you don't need to add special formatting.
```
### Log output
```shell
charmcraft login -h
Usage:
charmcraft login [options]
Summary:
Login to Charmhub.
Charmcraft will prompt for your Ubuntu One email address and password.
When you have successfully logged in, Charmcraft will store a token for
ongoing access to Charmhub at the CLI (if `--export` option was not used
otherwise it will only save the credentials in the indicated file).
If `--export <file>` option is used, a secret credentials file will
be created. And the file can be used to set `CHARMCRAFT_AUTH`
environment variable.
export CHARMCRAFT_AUTH=$(cat secret)
This is suitable for Linux environments without a Vault, such as
remote servers and CI/CD pipelines.
Please ensure the secret file and environment variable are secured.
Remember to `charmcraft logout` if you want to remove that token
from your local system, especially in a shared environment.
If the credentials are exported, they can also be attenuated in
several ways specifying their time-to-live (`--ttl`), on which
channels would work (`--channel`), what actions will be able to
do (`--permission`), and on which packages they will work
(using `--charm` or `--bundle`).
See also `charmcraft whoami` to verify that you are logged in.
Options:
-h, --help: Show this help message and exit
-v, --verbose: Show debug information and be more verbose
-q, --quiet: Only show warnings and errors, not progress
--verbosity: Set the verbosity level to 'quiet', 'brief',
'verbose', 'debug' or 'trace'
-V, --version: Show the application version and exit
--export: Export the Charmhub unencrypted secret credentials
to a file
--charm: The charm(s) on which the required credentials would
work (this option can be indicated multiple times;
defaults to all)
--bundle: The bundle(s) on which the required credentials
would work (this option can be indicated multiple
times; defaults to all)
--channel: The channel(s) on which the required credentials
would work (this option can be indicated multiple
times, defaults to any channel)
--permission: The permission(s) that the required credentials will
have (this option can be indicated multiple times,
defaults to all permissions)
--ttl: The time-to-live (in seconds) of the required
credentials (defaults to 30 hours)
See also:
logout
names
register
unregister
whoami
For a summary of all commands, run 'charmcraft help --all'.
For more information, check out: https://documentation.ubuntu.com/charmcraft/4.4.1/reference/commands/login
```
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| qwen3.6-35b-a3b-mtp-q6 |
Impact:
60
Quick Win:
42.0
Staleness:
5
Complexity:
30
Confidence:
80
Support Request:
0
|
needs triage | Charmcraft CLI help text generates invalid documentation links using full version numbers (e.g., 4.4.1) instead of stable or major version, causing 404 errors. | |
| qwen/qwen3.8-27b |
Impact:
30
Quick Win:
22.5
Staleness:
5
Complexity:
25
Confidence:
80
Support Request:
5
|
needs triage | Charmcraft help output generates documentation URLs with the full CLI version (e.g. 4.4.1) instead of a valid docs path, causing 404s. Freshly reported, no labels or maintainer response yet; root cause is the {version} placeholder in docs_url in charmcraft/application/main.py. |
Update history
| Date | Change |
|---|---|
| created |
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #2865 docs: charmcraft release reference is badly formatted | charmcraft | open | Documentation for `charmcraft release` command has formatting issues: `<None>` placeholders in usage, unformatted channel examples, and broken resource example formatting. | |
| #1498 docs: Fix 404 in charmcraft.yaml.j2 | charmcraft | closed | Merged to fix a 404 error in charmcraft.yaml.j2. The single-line change resolved the broken documentation link. Closed without reviews or CI checks. |