I would suggest putting the main CONTRIBUTING.md in the root of the repository. This folder is way too hidden.

Yes, i'm totaly on your side with this. The placement can be discussed and is not final i think.

I agree with this. Github has native support when the file is placed in root, see https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors

E.g. it is shown, when a new PR is opened to new contributors.

@andygrunwald as i read it, also /docs or /.github are allowed/used for this.

Without more context it is unclear what the meaning of this sentence is (yes I know it is the call to build.func)

Its better explained int App.md. Maybe remove it here

Yes after going through the rest of the files that would make a lot of sense. It is not important here (yet)

Same as the other file

While I love the context of why this document is important, I would like to raise the question if a description on why Coding standards are usefule is really needed.

I think we can assume a basic knowledge of software engineering to people who aim to read this doc.

I think it is helpful to keep the barrier for contribution low. A crisp document that brings the message across helps here.

My suggestion: Removing the chapter "Why Coding Standards Matter"

Yeah seems resonable. I had a look around what other documents like this one look like and found in many places somethings like these.

I think this sentence can be dropped.
It is in the similar context as the "why coding standards are useful".

Additionally, I don't know why I need to "please refer to this guide" when I am opening a PR. This doc are the guidelines to follow to create a PR. If a PR is not matching these guidelines, the feedback will be in this direction.
Not sure if adding a link to a PR to this doc helps. Rather than a checkbox in the PR template like "Followed and applied Coding standards" may be enough.

Why removing this paragraph?
It doesn't really add new information on what Coding standards itself. Following the rule of keeping it crisp and less is more.

Yeah, like above, on second tougth it seems a bit overengineered.

I like the recommendation overall. However, i think many engineers have their opinionated IDE. Thats why I think we should not "phrase it as mandatory" (this is how I read it).

What I can think about: Having a section like:

## IDE setup

Depending on your IDE, here are some recommendations for IDE configurations supporting you in development.

### VSCode

<Recommended extensions here>

### vim

....

This way, it feels optional and other people can add other IDEs.
Furthermore, I suggest that this is an own document like ide.md.

It is only a recommendation, as stated on line 35. I personaly use neovim mostly and adapted it so it fits. But i think that with one example as recommendet is more then enough.

Hahaha I had a similar comment written earlier today but decided against adding it. For a couple of reasons:

1. It is nice to choose a single IDE in your contributor guide, that way you don't have to answer questions from people when they try something else (thus making it non-optional in the guide)
2. Any seasoned (and thus stubborn) engineer will still try to use their own IDE anyways (looking at myself in the mirror), but they probably also know what they're doing
3. Any code style guideline should be in place using CI pipelines and with clearly defined tools to be able to enforce that if people use other IDEs they can still contribute while conforming to the same standards

I like the idea to start a new script from a template.
Why not going all in and providing the CLI commands for this?

If you plan to implement a new application script, use our templates to get a kickstart:

$ NEW_APP_NAME="my-script"
$ cp ct/AppName.sh ct/${NEW_APP_NAME}.sh
$ cp ...
$ sed ... (some git remote -v magic to get the fork path)

This way, folks can just copy / paste the commands and get going.

Additionally: Considering the CONTIRBUTING.md is the entry doc, this is the first time it is mentioned that we operate on a fork.
Maybe it is better to move this chapter to a

Guide: Create your own App Script

which starts with

1. Fork this Repository
2. Kickstart your app with your template
3. ...

There has been a proposal by @quantumryuu for this already, have a look here: https://github.com/community-scripts/ProxmoxVE/tree/new_script_testing/.github/CONTRIBUTOR_GUIDE/dev-scripts
I will start testing, experementing with this when the hollidays are over.

I also would love to have something simillar to this for Appname.sh and AppName-install.sh

About the AppName.sh/AppName-install.sh we could modify the scripts I proposed into asking things like "Author", "Source", "AppName" I guess.

Maybe it make sense to extract this to a structure.md.
This document can explain

• the folder structure or this repository
• the structure of some key files (e.g. function libraries)
• the structure of an application (which files build an application) <- that's the two paragraphs here

I‘m against splitting it up even more. There should be one seperate file for every script type and one general one to not overcomplicated it.

Here i am a bit lost. Where do I start now to build my own script? Here or with the template of ct/AppName.sh and install/AppName-install.sh?

Overall this sounds like the typicall GitHub Flow style, which is reasonable.
Only Step 4 is special to this repository.

What do you think about this suggestion:

1. Making a small guide "Setting up your development environment" -> This is essentially Step 4
2. For the rest, refer to guides like https://github.blog/developer-skills/github/beginners-guide-to-github-creating-a-pull-request/

I think we will never do a better job than the Github docs in the regular content. I think we should keep the focus on the repo and create visibility on what is special here.

We are thinking about the contribution procces for the Pull Requests. It is not really practical how it is done at the moment, as you can not test the functionality of the script besides running code from an unknown repo or coppying the code to your one repo for testing. I would leave this as is atm.

Whats the purpose of this chapter?
What goes in here? What does not go in here?

I think all relevant pages are linked above in the respective context. I am suggesting to drop this chapter.

Just out of curiosity. Why snipeit? Is this a very easy example?
I am asking, because a more popular application may create more engagement. I, at least, don't know "snipeit".

It just happens to one of my one scripts, so i know it best^^. Also it is not to complicated/long and inlcudes almost all topics wich are in the guides. This can always be changed of course.

Why is the author needed?
Afaik by contributing upstream + the git history, this is an outdated information very soon.
I also ask myself in which situation this will help?

Does this imply things like no whitespace, no special chars, etc.?

I ´think only whitespaces would be a problem, we have a couple with -.

A good and a bad example might be good here.
What does "overdo" mean? How many tags are too much? Is there a proxmox length limit?

There is no hard limit on the proxmox side. Its just there as some sorte of information.

I think this chapter can be removed. This file is more a "rundown of an install script".

This checklist may be helpful in the PR template.

I think it is better placed here. When you finished your script and are at the bottom of the guide you can check yourself. This would make the PR template to convoluted i think.

This script seem to be a "I am explaining each line in this install script". If this is the purpose, I may suggest an alternative approach to this:

Copying the whole script in this markdown file and using bash comments to add the relevant documentation context.

The current structure is hard to follow as the reader is not having the script in front of him/her. It is broken down in chapters. While commenting https://github.com/community-scripts/ProxmoxVE/blob/main/ct/snipeit.sh in full length, the reader is having the context visible.

E.g.

[...]
APP="SnipeIT"
var_tags="assat-management;foss"
var_cpu="2"
var_ram="2048"
var_disk="4"
# The operating system. Possible values are alpine, debian, ubuntu
var_os="debian"
# ...
var_version="12"
var_unprivileged="1"
[...]

Put sometimes you only need a short reminder of how to do handle the credentials, or how to do handle config files. If there is one finished script with comments, this would always be copied and things get left in there for no reason. This should not be a step by step guide for a script, more a how we do things here type of documentation. We could not ever explane any case in one finished script.

This is nearly what I suggested with "the documented version" (see above).

I think this file should not be here as a single file, but included in the markdown file.

Same suggestion as above with the "inline comment version"

I think it would be good to note that this is not enough. There is also a hard-link from the build.func file into the install script: https://github.com/community-scripts/ProxmoxVE/blob/main/misc/build.func

So to make sure that you actually test your own code (and I just found this out the hard way) you also need to change that.

Check this comment.
The scripts I've created, replace every URL!
On my end it works, and I can start creating helper scripts really fast without having to remember to change the links etc.

Nice! We can resolve this comment then