docs: add a note to our tutorials about the confusing concierge output#2393
Conversation
tonyandrewmeyer
left a comment
tonyandrewmeyer
left a comment
There was a problem hiding this comment.
I would much rather we just fixed the issue in Concierge.
Me too, but the issue has been open in Concierge for 6 months, so a note to help people in the meantime seems reasonable. |
dwilding
left a comment
dwilding
left a comment
There was a problem hiding this comment.
I'm in favour of this as a temporary addition. Concierge is causing confusion and we're still at least a release cycle away from an improvement.
| This first installs Concierge, then uses Concierge to install and configure the other tools (except tox). The option `-p k8s` tells Concierge that we want tools for developing Kubernetes charms, with a local cloud managed by Canonical Kubernetes. | ||
|
|
||
| This step should take less than 15 minutes, but the time depends on your computer and network. When the tools have been installed, you'll see a message that ends with: | ||
| This step should take less than 15 minutes, but the time depends on your computer and network. As `concierge` runs, you may see a number of messages that appear to be errors, like `ERROR controller ... not found`. Don't worry about these, they're because of how `concierge` currently exposes the output of the commands it runs internally. You only need to worry if your `concierge prepare` call fails -- then you should investigate the output, and reach out to us if you can't solve the problem yourself. When the tools have been installed, you'll see a message that ends with: |
There was a problem hiding this comment.
Nice.
I would personally use a different form, if there's more than one kind of message:
The following errors are transient:
ERROR controller ... not foundyada yada bleh lbeh
There was a problem hiding this comment.
Good idea, but I think it's best not to try to be exhaustive here, just give an idea of the general type of problem, especially as this is intended as a temporary solution.
|
Let's be careful here -- as discussed in daily, I'd really like us to spend our time pushing and reviewing a Concierge fix rather than reviewing temporary "doc workarounds". It's possible we could have had the fix already if we'd focussed our effort there. If that fix turns out to be much larger than we expect, we can revisit a doc workaround. |
I get what you're saying and don't disagree, in general. In this instance, we already have the doc update from James, and the tutorials are high visibility. Two instances of confusion related to this have been raised within the past week. I'd still push for publishing the workaround in this instance, if Tony is onboard. |
"Release cycle" is < 1 month, though. That's not really that long. And if this really is critical, then we could do a bug fix release mid-month. (I'm not convinced it is).
Unfortunately, Tony is not. I agree with Ben: let's just fix the problem, not document that there is a problem. I think it's confusing, but not exceedingly so. I already said last week that I'd prioritise getting this done before Nhan starts, so we can be confident that it'll be in the next release of Concierge, and (as above) could always push out an extra release if needed. I think documenting problems where we can fix them, instead of just putting the effort into fixing them, is a bad precedent for how our team spends time, and also gives a bad impression of the tools we produce. |
5 participants
We plan to improve
conciergeoutput in future, but right now it confuses users who follow our tutorial. This PR adds a note about the "error" messages to setup step. This can be reverted when we address this inconcierge.