Documentation-First Development
michaelgugino opened this issue · 13 comments
Multiple times per release, we are seeing escalations related to 'bugs' as perceived by users. Frequently, these bugs pertain to specific installation and cloud provider options. For one reason or another, different users have the perception that missing features are actually bugs because some place in the documentation gave them some high-level steps about how to perform some particular action, but not all components are able to handle such a configuration.
In order to better define what we actually support, feature work should point to publicly facing documentation. Chicken and egg problem aside (which can be resolved, hopefully, with some kind of automation), before a feature gets merged, it should have reference to public facing documentation.
If a given setting or option is not explicitly called out in our documentation, it should not be considered supported. No setting or option should make it into documentation without architectural review to ensure that all the different components impacted will be updated or assuring existing capabilities cover documented processes.
This is a recurring issue on UPI installations.
To give a recent example, a shared VPC in GCP for a UPI install. The documentation said it was supported, but there is no relevant section about how to configure the machine-api: https://docs.openshift.com/container-platform/4.5/installing/installing_gcp/installing-gcp-user-infra-vpc.html
Issues go stale after 90d of inactivity.
Mark the issue as fresh by commenting /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.
Exclude this issue from closing by commenting /lifecycle frozen.
If this issue is safe to close now please do so with /close.
/lifecycle stale
Stale issues rot after 30d of inactivity.
Mark the issue as fresh by commenting /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.
Exclude this issue from closing by commenting /lifecycle frozen.
If this issue is safe to close now please do so with /close.
/lifecycle rotten
/remove-lifecycle stale
Rotten issues close after 30d of inactivity.
Reopen the issue by commenting /reopen.
Mark the issue as fresh by commenting /remove-lifecycle rotten.
Exclude this issue from closing again by commenting /lifecycle frozen.
/close
@openshift-bot: Closing this issue.
In response to this:
Rotten issues close after 30d of inactivity.
Reopen the issue by commenting
/reopen.
Mark the issue as fresh by commenting/remove-lifecycle rotten.
Exclude this issue from closing again by commenting/lifecycle frozen./close
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.
/reopen
@michaelgugino: Reopened this issue.
In response to this:
/reopen
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.
/remove-lifecycle rotten
Issues go stale after 90d of inactivity.
Mark the issue as fresh by commenting /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.
Exclude this issue from closing by commenting /lifecycle frozen.
If this issue is safe to close now please do so with /close.
/lifecycle stale
Stale issues rot after 30d of inactivity.
Mark the issue as fresh by commenting /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.
Exclude this issue from closing by commenting /lifecycle frozen.
If this issue is safe to close now please do so with /close.
/lifecycle rotten
/remove-lifecycle stale
I like this but I'm not in a position to push it forward, are you @michaelgugino ? I guess if not we can let it autoclose as a good idea we weren't able to allocate time to pursue.
Rotten issues close after 30d of inactivity.
Reopen the issue by commenting /reopen.
Mark the issue as fresh by commenting /remove-lifecycle rotten.
Exclude this issue from closing again by commenting /lifecycle frozen.
/close
@openshift-bot: Closing this issue.
In response to this:
Rotten issues close after 30d of inactivity.
Reopen the issue by commenting
/reopen.
Mark the issue as fresh by commenting/remove-lifecycle rotten.
Exclude this issue from closing again by commenting/lifecycle frozen./close
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.