Suggestion: document the supported features

[dirkhh]

OK, this is possibly my own fault for missing the forrest for the trees, but I can't seem to find documentation of the config file syntax and especially which features are actually supported. There are a couple of examples, but... is there documentation somewhere that I just didn't see?

Expected Behaviour

An easy to find section in the documentation that tells me more about the syntax of the config file and the supported features.

Current Behaviour

I looked on GitHub, I git-grep-ed through the sources, I couldn't find it - and am very worried that @alexellis will respond to this issue saying: look, there...

Context

A new user of the bot might benefit from easy to find documentation...

Your Environment

• You're using the hosted Derek service

or

• You host your own OpenFaaS cluster with Derek installed

[alexellis]

For now the README.md is the documentation, but perhaps it could be improved or re-written. Maybe it should be less verbose and we add a USER GUIDE.md file?

A docs site is a nice idea, but rather arduous to do properly - generally to do it right we'd want a domain name, clear landing page (and a designer to make that) and then a docs site generated by mkdocs for which we'd have to choose a theme we all liked and setup a CI/CD pipeline to populate it. Netlify works well for the OpenFaaS docs.

For the YAML syntax, the approach we are using is to turn everything on and then specify a list of maintainers, the word curators is an alias that can be used in its place. Was there something specific you were looking for Dirk? I think the PR I submitted to Subsurface has everything turned on already. The milestones feature is on by default when commenting is enabled.

[dirkhh]

• I think a UserGuide.md would be great. I don't think you need a doc site for such a relatively small project
• the syntax - let's just say I'm confused which shows that maybe it isn't as clear as you think... I thought only things that you enable under features are enabled and I was looking for the right keywords to use there. And I couldn't find it.

If you look at https://github.com/Subsurface-divelog/subsurface/blob/master/.DEREK.yml we try to explicitly enable things. Are we doing this right? I don't know.
Also, Derek doesn't listen to @sfuchs79 who is clearly listed as a maintainer. See subsurface/subsurface#1507
Is there a way to get error messages from derek sent back to the project? Syntax errors, whatever it is that is causing this to fail?

[rgee0]

Currently the features are documented in GET.md. The features aren't as granular as you may be expecting. Essentially there are two - dco_check & comments. comments covers everything you can do from a comment on an issue and PR conversation. #22 shows where we were aiming to get to.

Can you ask @sfuchs79 to try one line at a time?

[dirkhh]

The features aren't as granular as you may be expecting. Essentially there are two - `dco_check` & `comments`. `comments` covers everything

Which would be nice to have explicitly documented...

Can you ask @sfuchs79 to try one line at a time?

He did. Look towards the end of the comment thread. And then I entered the exact same command and that worked.

[dirkhh]

This is perfect. Thank you so much for adding this

[alexellis]

You're welcome. I think we have that covered above now.

I saw sfuchs79 try the command before you did, but I need sfuchs79 to do it again because I can't find his message in the logs. Ideally with some other label or removing the label. Hoping that it either works as expected or I get a log item this time.

Alex

[dirkhh]

He just did