Automerge documentation misleading to a newbie

[JimBacon]

Hi

Thanks for Renovate. It might turn out to be a useful thing if I can figure it out. I just had a light bulb moment when I realised it takes Renovate multiple runs to achieve its ends. The documentation for automergeType, in particular, misled me. It says

If you prefer that Renovate more silently automerge without Pull Requests at all, you can configure "automergeType": "branch". In this case Renovate will:

• Create the branch, wait for test results
• Rebase it any time it gets out of date with the base branch
• Automerge the branch commit if it's: (a) up-to-date with the base branch, and (b) passing all tests
• As a backup, raise a PR only if either: (a) tests fail, or (b) tests remain pending for too long (default: 24 hours)

I assumed that would all happen in a single pass because nothing told me otherwise.
I would not have made this error if, instead, it had said something like

Renovate will

• Create the branch and push changes on the first run which will initiate the tests that your CI performs
• Rebase, on subsequent runs, if it is out of date with the base branch, yet again initiating your tests
• Automerge the branch commit when a run finally occurs which finds (a) the branch is up to date with the base branch, and (b) CI has completed and all jobs succeeded
• As a backup, raise a PR when a run finds that either: (a) tests failed, or (b) tests remain pending for too long (default: 24 hours)

I haven't found a page in the documentation which gives an overview of how Renovate is intended to work. I've found myself reading through all the config options and trying to assemble an understanding from that. It wasn't until I read through renovatebot/config-help#933 that this revelation came to me. Maybe it is documented somewhere and I missed it but it could be something that is just so blindingly obvious to the developers that it has been omitted.

It was like we were going on a date and you said you were going to wait for me in the cafe. It turns out that actually you meant you were going to pop in once a day just to see if I was there. Caused me some heartache and I nearly walked out on you but, now I know, we might be able to get along.

[rarkins]

The challenge is that we if we added an extra paragraph explaining the basics of how Renovate works/runs to every single config option such as automergeType then it would be bloated and duplicated.

I don't think that description is particularly bad, but a better "Getting Started" doc for Renovate would probably do a lot of preventative good.

FYI there is further automerge documentation available here: https://github.com/renovatebot/renovate/blob/master/docs/usage/automerge-configuration.md

[viceice]

After docusaurus: We should add some cross links from automerge related settings to automerge doc and maybe vice versa.

[JimBacon]

Thanks for the reply. I totally agree that you should avoid bloat and duplication. I like my documentation DRY too.

I think you are right that a description of the principles of Renovate and a structured explanation how to configure it in the 'Getting Started' section, with links to the configuration options, would have really helped me.

At present 'Getting Started' is more about installation and there is a bit of a gap when it comes to giving the first-time user an introduction and understanding.