Add docs for all types of releases #6210
Conversation
calebcartwright
added
self-hosting
|
doc/releases.md
Outdated
|
|
||
| This Shields server is the exact same codebase that powers the main Shields.io service; we do not have a separate self-hosted version of Shields. This means that the server codebase is geared towards the development, maintenance, and operation of the Shields.io service so there are a few things to note: | ||
|
|
||
| - We often have to reject or de-prioritize feature requests that are only applicable for self-hosting and/or which may be problematic for the core Shields.io offering (e.g. requiring auth on the badge server) |
There was a problem hiding this comment.
I think in the ops meeting we said something about we're happy to host docs/tutorials around some of this stuff. We just won't usually merge PRs to core for features that are only applicable to self-hosted instances or irrelevant for users of shields.io itself. Shall we add that here.
There was a problem hiding this comment.
Yeah I think this is the right general area to call that out. I'll have a go and see if that works better inline literally here or if it'd be worthwhile to have a block of its own, as I'm thinking it'd be good to actually solicit that type of feedback/story docs
There was a problem hiding this comment.
Added as a separate paragraph in the same section. Let me know what you think, e.g. if it'd be better as another bullet item, etc.
doc/releases.md
Outdated
| - We do not accept new badges that cannot be utilized with Shields.io (e.g. those that would always require user-specific authorization) | ||
| - We do not do any additional testing nor validation of self-hosted instances (e.g. we test Shields.io with Jira Cloud badges, but we don't test a self-hosted Shields server against a self-hosted Jira server instance with auth) | ||
| - We're happy to try to offer some tips and guidance to self-hosters when and where we can, but we don't have the ability to troubleshoot/debug/support/etc. self-hosted Shields servers | ||
| - Note that we may offer some sort of paid support arrangement in the future for those that would be interested |
There was a problem hiding this comment.
On this last point "paid support arrangement".. I know one maintainer has done this, but this is definitely not a service I offer and I wouldn't want to be contacted by someone asking for it. Dunno where you stand on it.
I think if we're going to formalise this its important to specify who to contact about this/on what basis/etc rather than this which is a bit woolly. If we're not in a position to do that (yet), lets drop the mention of it, at least for now.
There was a problem hiding this comment.
On this last point "paid support arrangement".. I know one maintainer has done this, but this is definitely not a service I offer and I wouldn't want to be contacted by someone asking for it. Dunno where you stand on it.
I think if we're going to formalise this its important to specify who to contact about this/on what basis/etc rather than this which is a bit woolly. If we're not in a position to do that (yet), lets drop the mention of it, at least for now.
Good point, I'm definitely in the same boat myself as far as my willingness/capacity for this. @paulmelnikow has brought this possibility up a few times (including a few more times of late) and then of course it actually happened so it seemed like it was picking up some steam.
Paul if you're in a position where you'd like to offer this paid support stuff then I'm happy to try to frame the wording here (provided you can share whatever contact channel), but if this is still an unknown or a possible-but-not-yet ready then I'd agree with Chris and will remove
There was a problem hiding this comment.
I've done this once, and am willing to do it again. I don't have a web page up or any streamlined way to pay for a support request, so for the moment I think it is okay for folks who want this to email me at paul@m6ize.com. I'm happy to include that here if it makes sense to other folks.
There was a problem hiding this comment.
Tweaked this text to point them specifically to you Paul. Used the same pattern we added to the CoC with a badge for the email address, but happy to change this to standard link/mailto if you'd prefer
| - We often have to reject or de-prioritize feature requests that are only applicable for self-hosting and/or which may be problematic for the core Shields.io offering (e.g. requiring auth on the badge server) | ||
| - We do not accept new badges that cannot be utilized with Shields.io (e.g. those that would always require user-specific authorization) | ||
| - We do not do any additional testing nor validation of self-hosted instances (e.g. we test Shields.io with Jira Cloud badges, but we don't test a self-hosted Shields server against a self-hosted Jira server instance with auth) | ||
| - We're happy to try to offer some tips and guidance to self-hosters when and where we can, but we don't have the ability to troubleshoot/debug/support/etc. self-hosted Shields servers |
There was a problem hiding this comment.
Some of the wording I came up with yesterday, maybe to incorporate somewhere around here:
Spotted something wrong? Why not step up and help us fix it by submitting a pull request? All community contributions, even documentation improvements, are welcome!
There was a problem hiding this comment.
I really like the theme of this as we discussed in the previous Ops meeting, so I elected to pull this up to the very top of the doc since it's really applicable to the entirety of the Shields project (not just self-hosting). In doing so I did tweak the wording slightly so please let me know what you think!
calebcartwright
removed
the
needs-discussion
|
I think ec7b71d incorporates all of the above feedback along with a few other points from offline discussions. Going to mark this as ready for review, though won't be surprised at all if we still need to iterate on this |
calebcartwright
force-pushed
the
release-docs
branch
from
ec7b71d to
eba74c7
Compare
doc/releases.md
Outdated
|
|
||
| We do not have a fixed schedule for deploying updates to the Shields.io production environment, but we typically deploy the latest version at least once per week. | ||
|
|
||
| We do not have any guaranteed SLA for the Shields.io service, but we do have monitoring and observability capabilities in place and our [Operations team](https://github.com/badges/shields#project-leaders) will review an address any availability, performance, etc. issues on a best-effort basis. |
There was a problem hiding this comment.
yeah aside from this one minor copy edit I'm happy to give this the 👍 and I'll go back and have a quick look at the self-hosting docs in this light.
There was a problem hiding this comment.
oops, good catch! 5fdc259
calebcartwright
force-pushed
the
release-docs
branch
from
5fdc259 to
30e622c
Compare
calebcartwright
force-pushed
the
release-docs
branch
from
30e622c to
5276961
Compare
Opening this as a draft, both because there's some additional discussion needed to determine if this is a route we want to take, as well as the fact that it'd likely need some additional wordsmithing, accompanying updates in some other files etc. in order to proceed
The core idea is to document the different things we release along with any relevant info. IMO this is quite beneficial for the sake of clarity for the self-hosting case, but will also be beneficial in others (documents an answer to questions like "how frequently do Shields.io deploys happen). This heavily steals from the great work @chris48s did in #6156 but with a proposed additional section from me on self-hosting.
Some outstanding questions I have: