Documenting known issues¶
The docs describe the code as it behaves today. When that differs from the intended behaviour, say so in the page, and link a tracking issue so the notice can be removed when the issue is closed. Do not present intended behaviour as fact, and do not leave a bug that changes how a reader should use the code undocumented.
Discrepancies found while writing the docs are collected in #266; each has its own child issue.
Which notice to use¶
| Situation | Treatment |
|---|---|
| Bug that will be fixed | A Known issue warning next to the behaviour. |
| Setting that is declared but not read | In the settings table: "Declared, currently has no effect (#NNN)". |
| Behaviour not decided yet | A Behaviour may change note that states what the code does today. |
| Packaging problem (no-op extra, missing dependency) | A short note in the page's install section. |
| Stale README or comment | Fix it. No docs notice. |
| Security-relevant | Triage and fix before describing it on the public site. File the issue, but add no public notice. |
Format¶
Use one admonition per issue at each place it applies, with the issue number in the title so notices can be found with grep -rF 'Known issue ([#' docs (and grep -rF 'may change ([#' docs for the other kind):
!!! warning "Known issue ([#273](https://github.com/msflib/fastapi/issues/273))"
`VerificationResult` has no `raw` field, so the `raw=` value both gateways
pass is dropped. The returned result does not expose the provider response;
call the provider's API yourself if you need it.
For behaviour that is undecided:
!!! note "Behaviour may change ([#267](https://github.com/msflib/fastapi/issues/267))"
Scope profiles require `tenant_id` but allow a null `workspace_id`.
State what happens now, give a workaround if there is one, and keep it short. One notice may list the closely related limitations that a single issue tracks (for example several gateway problems tracked in one payments issue); split it if they affect different parts of the page.
Rules¶
- One issue per item. Put a notice next to each behaviour the issue affects, so one issue can have several notices across a page or the site (for example one core issue shown on several core pages). Do not repeat the same notice for the same limitation twice on one page; refer back to it in prose instead.
- A PR that fixes an issue listed in #266 also removes or updates its notice and ticks the box in #266.
- If you are not sure whether the code or the intent is right, file a decision issue and use the "may change" note.