Contributor Guide

[dsiebel]

I created a couple of PRs to this repo as well as its predecessor, and each time I was confronted
with messages like "this is not the way we do it", or "look at the other scripts".
The latter is exactly what I did before creating each of the PRs, just the wrong ones, apparently.

I totally get the whole "Pull requests submitted against main are meticulously scrutinized"-philosophy,
and I am a big fan of clear language, but the experience so far left me wondering:

Is there an official contributors guide that supports these comments?
I am specifically looking for documentation that clearly describes:

• how to develop update- and install-scripts
• which scripts can be used as blueprints / inspiration
• what exactly are the "established patterns and conventions" the CONTRIBUTING.md refers to?

If this doesn't exist, yet, are the maintainers willing to (co-)create one?

Just to be clear: I am not complaining here, just trying to improve the contributor experience.

[MickLesk]

The fact is, there is currently no guide, but there will be one. There are still some discrepancies, so there is no timetable.

Some proposals have currently failed, each of us is in a full-time job on the side and then there is the amount of PR's that are currently taking everything.

We will probably have to introduce a PR freeze for 1-2 weeks so that we can concentrate on specific topics.

I'd be happy to discuss this further on Discord if you write to me.

[dsiebel]

Yeah, I am in the same boat job-wise. I am happy to help out where I can.
I haven't looked into the Discord community so far, mainly because my AdBlocker blocks the account verification link 😅
Will try again later.

[andygrunwald]

Glad that this discussion is happening.

I am in the same boat as @dsiebel as it is hard "to get into". I think a PR Freeze is reasonable with the goal of having a basic guide. On the other hand, it doesn't need to be perfect from the get-go, but can be developed in an iterative approach.

What I am especially looking for in such a COntribution Guide (or maybe docs in general):

• Folder and File-Structure with explanation (what belongs where and why)
• Legend and wording (e.g. CT == Container, etc.)
• A guide on how to develop your first application script
• How to test changes locally / in a setup (what setup is needed?)

On how to structure docs, the https://diataxis.fr/ framework has been proven to be helpful in many bigger projects:

On the way how to present the docs:
I would love to see a website, easy to access and to render. https://astro.build/ or https://docusaurus.io/ are great tools for this and easy to manage. However, this is additional effort. Maybe a simple docs/ folder with Markdown files is a pretty good start.

I see in https://github.com/community-scripts/ProxmoxVE/tree/contributor_guide/.github/CONTRIBUTOR_GUIDE that the Contributor guide is placed in the .github folder. I think this is a pretty uncommon location for it. Additionally, on some OS, the .folders are invisible by default (in explorer views).
Maybe a good idea is to move it to the / level of the repository.

Long story short: I would like to help, especially with proof reading and testing of the guides. I am not familiar with the codebase itself, which makes me a good candidate. Would it make sense to split the #920 PR a bit to make it easier to review and iterate?

[michelroegl-brunner]

Would be nice if you would take the time and proof read the docs in the PR. The location of the files can easily be changed and i agree with you that it should be in /DOCS or something. I also think we should not overcomplicate it atm and keep it simple as markdown files in the repo. Maybe we can add i sometime to the Frontend, but im not sure this is entierly nessecery.

You can always have look at the files, changes things around as you see fit and open a PR against the contributing_guide branch.
I hope we have something to publish here when the holidys end.

[andygrunwald]

Will try to do in the next days.