Key concepts sidebar for dashboard, scheduling, grouping, automerge

[HonkingGoose]

Describe the proposed change(s).

Introduction

I wanted to put my new dependency dashboard showcase page under the getting-started section, but @rarkins had a way better idea:

I don't think we should overload Getting Started too much. I think we have some core concepts like dashboard, scheduling, grouping and automerge which could together be in a common folder, such as "Key Concepts"?

I really, really like their idea to have a "Key concepts" folder! It's really clean how scheduling, grouping, automerge, and dependency dashboard all can go under that category! This also makes it easy to see how those features interact and how to cobble things together for best effect.

So the new user of Renovate can read the getting started docs to get a basic overview, and then they can deep-dive into topics they find valuable via the key concepts folder/sidebar.

Scope

This is a big rework, and it will need to be done in chunks, as doing it all at once will block everybody from adding new docs via PRs or make changes while the Renovate team is working on the docs.

Todo's

Draft todo-list to keep track of the necessary changes. This list will get updated as needed:

• docs: create dependency dashboard showcase page #11183
• docs: create page for key concept scheduling #11278
• docs: move automerge deep dive to key concept section #11490
• Review key-concepts/automerge.md for suitability for newcomer to this feature docs: improve key concepts automerge #11639
• Create page key-concepts/presets.md that covers in repo presets and global presets, nudge people with many repos to configure a global config, so they can set things like dependencyDashboard to true or false for all the repos under their control
• Create page key-concepts/grouping.md (Incorporate tip: How to utilize "group:allNonMajor" and "group:nodeJs" presets simultaneously? #11572 (comment))

Migrate content process:

I think something like this would work OK-ish:

• Pick a key concept, and decide what things we want/need to highlight
• Migrate existing content for that concept into the new page where needed
• Update outdated links

I'm open for suggestions on a better workflow/process!

TLDR:

Big documentation rework, with the goal to make it easier to learn about some big concepts of Renovate. We should decide what we want to show/highlight in these pages, and then we'll need to work on migrating content, fixing links, etc.

[rarkins]

@HonkingGoose if you can add a docs/usage/key-concepts/dashboard.md file then I'll fix up the docs page to add the menu

[HonkingGoose]

@HonkingGoose if you can add a docs/usage/key-concepts/dashboard.md file then I'll fix up the docs page to add the menu

I've renamed the file in my draft PR #11183 to match your description. 😄

[HonkingGoose]

@rarkins Which page do you want first? Grouping or automerge?

[rarkins]

I think automerge, as we already have a page on it don't we?

[HonkingGoose]

We have this "deep dive" page on automerging already: https://docs.renovatebot.com/automerge-configuration/

Do you want to keep that deep dive? Or do you want to incorporate it in the key-concepts page for automerge?

[rarkins]

Let's move it to key concepts

[HonkingGoose]

Will do!

[HonkingGoose]

@rarkins Do you want grouping or presets to be up next for a new concepts page?

[rarkins]

I think presets

[HonkingGoose]

I'll wait until PR #11565 gets merged before starting work on the presets. No point in starting now and getting into a hell of merge conflict later... 😄

[HonkingGoose]

We're nearly done with this issue, we only need a key concepts page for grouping. But I'm not the right person to write key-concepts/grouping.md, as I'm not familiar enough with grouping to get it right. 😄

Are one of you maintainers willing to write a draft version? I'll help improve the draft by reviewing it, and adding my suggestions. 😉

[azro352]

Hi,
Something I found difficult to undestand when I tried to customize my use of renovate was the global workflow, the manager>datasource>versionning>updates things

That something you understand when you read the top sentence of the module pages but it came late

I'd like to propose a Key-concept: Global workflow, and here's a simplified sketch of it

flowchart LR
    C[For each manager:\ncollect files]
    C -->|managerA| D["[file1, file2]"]
    C -->|managerB| E["[file3, file4]"]
    C -->|managerC| F["[file5, file6]"]


    D  -..-> Z[...]

    E -->|file1| G[find datasource]
    E -->|file2| H[find datasource]

    F  -..-> ZZ[...]

    G --> I[compute versionning system]
    I --> J[find next valid update]

    H --> ZZZ[...]

    Z  -..-> PR
    J --> PR[Collect updates and setup the needed PRs]
    ZZ  -..-> PR
    ZZZ  -..-> PR    

• for each manager :
  • collect files
  • for each file :
    • get the associate datasources
    • compute the versionning to use
    • find the next valid update

[HonkingGoose]

@rarkins what do you think about the proposal to have a Key concepts, Global workflow page? I also find it tricky to get a good overview of the order in which Renovate does things in our docs. The current information is scattered over each Renovate Modules page.

[rarkins]

I think a "how does Renovate work?" type page with a high level overview should be good

[HonkingGoose]

Sounds good to me, but I'm not the right person to write a draft... I don't know enough about the internal behavior of Renovate. I'm happy to review the draft ofcourse. 😄

I'd like to keep the "How does Renovate work" part separate from this issue. @rarkins Can you create a new issue or discussion to hash out the requirements?