Dev|Docs: .otterdog template (.eclipsefdn-template)

[kairoaraujo]

The goal of this issue is to improve the users to deploy and use otterdog and the development experience while contributing to the project.

The proposal is to create/move the template from https://github.com/EclipseFdn/.eclipsefdn-template to https://github.com/eclipse-csi/.otterdog or https://github.com/eclipse-csi/.otterdog-template

• The renaming also will help to avoid confusion about the owner of the setup.
• The confusion between eclipse-csi and EclipseFdn organizations as the owner source of the project

Once it is moved/created update the documentation.

[kairoaraujo]

Note: I'm happy to move forward with this issue, but I don't have rights for the first part (create/move)

[netomi]

Fyi: there is the open-source project eclipse-csi/otterdog and the configuration for an actual instance of its use at EclipseFdn/otterdog-configs and EclipseFdn/otterdog-defaults. The .eclipsefdn-template repository is used by that instance, and it is not required to have when you want to use otterdog. So moving that repo to eclipse-csi does not really make sense imho.

[kairoaraujo]

Fyi: there is the open-source project eclipse-csi/otterdog and the configuration for an actual instance of its use at EclipseFdn/otterdog-configs and EclipseFdn/otterdog-defaults. The .eclipsefdn-template repository is used by that instance, and it is not required to have when you want to use otterdog. So moving that repo to eclipse-csi does not really make sense IMHO.

Let me check if understood it right.

As a user (not a developer), once I want to use otterdog on my organization I don't need to have the .otterdog or .eclipsefnd in my org?

[kairoaraujo]

Ok, I found it in a note here:

• https://otterdog.readthedocs.io/en/latest/usage/

So, my suggestion was to have a template for the user while deploying. I am still not sure if it is required, but would be an easy step for users?

[netomi]

First of all the config repo (.otterdog or .eclipsefdn) is not required to use otterdog. Its just a common place to store the configuration. You can perfectly keep it local as well as I do myself.

Then the .eclipsefdn-template is just the skeleton for that config repo for the use case of using otterdog within the EF. It is referenced here: https://github.com/EclipseFdn/otterdog-defaults/blob/main/otterdog-defaults.libsonnet#L437

It basically means that when otterdog is applied the first time for a new organization, it will create the .eclipsefdn repo automatically, and use the .eclipsefdn-template as a template to already setup a few common things.

Again, this is totally not necessary and just convenience for the EF.

[netomi]

In the example default config that you can use right away: https://github.com/eclipse-csi/otterdog/blob/main/examples/template/otterdog-defaults.libsonnet, there is no config repo included, so you can then create it yourself, or adjust the default config to your needs.

[kairoaraujo]

Hi @netomi , thank you for clarifying. It helps a lot. While the workflow seems straightforward for experienced Otterdog users, there's room for improving the onboarding experience for new adopters. As a new adopter, my initial approach was to follow the documentation, which led to some confusion when trying to manage my GitHub organization (and of course looking to EF default configuration usage). Based on this experience, I'd like to propose some documentation clarifications that might help other new users:

• A more easy explanation of the validation workflow - particularly how the validate command relates to both local files and GitHub configurations
• Step-by-step examples showing the complete workflow from initial setup to successful validation More explicit documentation about common error messages and their resolution

Would these additions be valuable for the project? I'm happy to contribute these improvements if you think they would help future users avoid similar confusion.

[netomi]

so better documentation is always welcome.

The outlined steps should rather be expanded with real examples on how to use the tool.

I did test it myself on one of my own orgs using the example default config and it just works out of the box like that, no additional setup required, but the individual steps should be better explained imho.