martin/ProxmoxVE
1
0
Fork 0
mirror of https://github.com/community-scripts/ProxmoxVE synced 2025-01-10 19:05:09 +00:00
Code Issues Actions 8 Packages Projects Releases Wiki Activity

Update CONTRIBUTING.md

Browse Source
This commit is contained in:
CanbiZ 2024-12-06 13:41:48 +01:00
parent 7a7b0facc1
commit 9ea997f18b
1 changed files with 203 additions and 195 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

398
.github/CONTRIBUTOR_GUIDE/CONTRIBUTING.md vendored
View File

@ -1,210 +1,218 @@
<div align="center">
<a href="#">
<img src="https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/images/logo.png" height="100px" />
</a>
</div>
<h2 align="center">Contributing to Proxmox VE Helper Scripts</h2>
Everybody is invited and welcome to contribute to Proxmox VE Helper Scripts. # Community Scripts Contribution Guide
- Pull requests submitted against [**main**](https://github.com/community-scripts/ProxmoxVE/tree/main) are meticulously scrutinized, so please do not take it personally if the project maintainer rejects your request. By adhering to the established patterns and conventions throughout the codebase, you greatly increase the likelihood that your changes will get merged into [**main**](https://github.com/community-scripts/ProxmoxVE/tree/main). ## Overview
Welcome to the community-scripts repository! This guide provides detailed instructions on how to contribute to the project, including code structure, best practices, and setup instructions for contributing to our repository.
- It is important to stress that complaining about a decision after it has been made is not productive behavior for the pull request submitter. It is crucial for all contributors to respect the decision-making process and collaborate effectively towards achieving the best possible outcome for the project.
- The repository will only accept Alpine applications that make use of the Alpine Package Keeper.
## Table of Contents
- [Getting Started](#getting-started)
- [Script Flow Overview](#script-flow-overview)
- [Important Files and Functions](#important-files-and-functions)
- [`AppName.sh`](#appnamesh)
- [`AppName-install.sh`](#appname-installsh)
- [`build.func`](#buildfunc)
- [`install.func`](#installfunc)
- [`create_lxc`](#create_lxc)
- [How to Contribute](#how-to-contribute)
- [Forking the Repository](#forking-the-repository)
- [Creating a Branch](#creating-a-branch)
- [Writing Clear Commit Messages](#writing-clear-commit-messages)
- [Submitting a Pull Request](#submitting-a-pull-request)
- [Good Practices for Issues and Pull Requests](#good-practices-for-issues-and-pull-requests)
- [Issue and Pull Request Templates](#issue-and-pull-request-templates)
- [Additional Resources](#additional-resources)
## Getting Started ## Getting Started
Before contributing to this project, ensure you have the following prerequisites: Before contributing, please ensure that you have the following setup:
1. **A Proxmox VE server or testing environment** for verifying your changes.
2. **Familiarity with LXC containers**, Proxmox, and **Bash scripting**.
3. **A GitHub account** and appropriate access to the repository.
## Script Flow Overview 1. **Visual Studio Code** (recommended for script development)
2. **Necessary VS Code Extensions:**
- [Shell Syntax](https://marketplace.visualstudio.com/items?itemName=bmalehorn.shell-syntax)
- [ShellCheck](https://marketplace.visualstudio.com/items?itemName=timonwong.shellcheck)
- [Shell Format](https://marketplace.visualstudio.com/items?itemName=foxundermoon.shell-format)
The Proxmox VE Helper Scripts follow a defined sequence when setting up an LXC container or performing other tasks. Here's an overview of the flow: ### Important Notes
- Use `AppName.sh` and `AppName-install.sh` as templates when creating new scripts.
- The call to `community-scripts/ProxmoxVE` should be adjusted to reflect the correct fork URL.
## Script Flow Overview ---
The Proxmox VE Helper Scripts follow a defined sequence when setting up an LXC container or performing other tasks. Here's an overview of the flow: ## Structure of Installation Scripts
1. **Main Command Execution** All installation scripts should follow this standard structure:
The process begins when you execute the following command:
```bash
bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/AppName.sh)"
```
2. **Calling `build.func`**
The **`AppName.sh`** script invokes **`build.func`**, which prepares the environment for installation and configuration.
3. **Executing `install.func`** ### 1. File Header
After the environment is set up, **`build.func`** calls **`install.func`**, which handles the installation of necessary software and configuration. ```bash
#!/usr/bin/env bash
4. **Creating the LXC Container (`create_lxc`)** # Copyright (c) 2021-2024 community-scripts ORG
Finally, **`install.func`** triggers **`create_lxc`** to create an LXC container with default values (disk size, CPU, RAM, etc.). # Author: tteck (tteckster)
# License: MIT
# https://github.com/community-scripts/ProxmoxVE/raw/main/LICENSE
```
5. **Container Creation Completion** ### 2. Initial Setup
The LXC container is created, and the process concludes by reporting the success or failure of the container setup. Every script should source the functions file and run these initial checks:
## Important Files and Functions
### `AppName.sh`
This is the main entry script for initiating the process. It is responsible for:
- Starting the installation by calling **`build.func`**.
- Calling **`install.func`** after system setup.
- Managing the flow to ensure the container is correctly created.
### `AppName-install.sh`
This script typically manages specific installation tasks, such as setting up software inside the container. It is invoked within **`install.func`**.
### `build.func`
The **`build.func`** function:
- Prepares the system environment.
- Installs necessary packages or tools.
- Verifies storage availability and prepares LXC templates.
### `install.func`
The **`install.func`** function:
- Handles the installation and configuration of software packages inside the container.
- Sets up user permissions, network interfaces, and other container settings.
### `create_lxc`
The **`create_lxc`** function:
- Creates the LXC container using Proxmox commands.
- Applies default configurations like disk size, CPU, RAM, and network settings.
- Reports on the success or failure of the creation process.
## How to Contribute
We welcome contributions to the project! Please follow the steps below to ensure a smooth contribution process.
### Forking the Repository
Start by forking the repository to your own GitHub account:
1. Navigate to the [repository page](https://github.com/community-scripts/ProxmoxVE).
2. Click the **Fork** button in the upper-right corner.
### Creating a Branch
Always create a new branch for your changes to avoid conflicts:
git checkout -b feature/your-feature
### Writing Clear Commit Messages
Ensure your commit messages are clear and descriptive:
- **Good example:** `Added support for custom disk sizes in create_lxc`
- **Bad example:** `Fixed stuff`
### Submitting a Pull Request
After pushing your changes to your fork, create a pull request (PR):
1. Go to the **Pull Requests** tab on GitHub.
2. Click **New Pull Request** and select the branch with your changes.
3. Provide a detailed description of your changes, why you made them, and what problem they solve.
## Good Practices for Issues and Pull Requests
To help ensure your pull request is accepted and that issues are useful, please follow these best practices:
### For Pull Requests:
- Ensure your code is **well-documented**.
- **Test** your changes on a Proxmox environment before submitting.
- Follow the **project’s coding style** and conventions.
- Link to any relevant **issues** if applicable.
### For Issues:
- Always provide a **clear description** of the problem.
- If reporting a bug, include steps to **reproduce** it.
- If suggesting a new feature, explain its **use case**.
## Issue and Pull Request Templates
We’ve set up templates to make reporting issues and submitting pull requests easier. These templates will guide you in providing the required information for issues and PRs.
### Issue Template
The issue template will ask for the following:
- Steps to reproduce the issue.
- Expected behavior.
- Actual behavior.
- Any error logs or relevant system information.
### Pull Request Template
The pull request template will ask for:
- A summary of the changes made.
- Any relevant issues the PR addresses.
- A description of how to test the changes.
These templates are automatically populated when you create a new issue or PR.
## Additional Resources
- [Proxmox Documentation](https://pve.proxmox.com/pve-docs/)
- [GitHub Documentation on Pull Requests](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request)
- [Open Source Guides: Starting an Open Source Project](https://opensource.guide/)
--
## Creating New Scripts
When creating new scripts for the ProxmoxVE Helper Scripts repository, we recommend using **Visual Studio Code** (VS Code) for a smooth development experience. Follow these steps and guidelines to ensure your contributions meet the project’s standards.
### Template Usage
Start by using the following scripts as templates for your new script:
- **`AppName.sh`**
This is the main script that handles the high-level flow and calls the necessary functions. It serves as the entry point for the process.
- **`AppName-install.sh`**
This script is typically used for the installation process within the container, handling the actual setup of software and services.
These templates help ensure consistency across all scripts and make it easier for contributors to follow the project's structure.
### Visual Studio Code Setup
To ensure high code quality and to avoid common mistakes, it's recommended to use the following Visual Studio Code extensions:
1. **Shell Syntax**
[Shell Syntax Extension](https://marketplace.visualstudio.com/items?itemName=bmalehorn.shell-syntax)
This extension adds syntax highlighting and IntelliSense for shell scripts, making it easier to write and read your Bash scripts.
2. **ShellCheck**
[ShellCheck Extension](https://marketplace.visualstudio.com/items?itemName=timonwong.shellcheck)
ShellCheck is a static analysis tool for shell scripts. It helps identify common errors, potential issues, and improvements in your scripts. It runs automatically as you write your script and provides useful suggestions.
3. **Shell Format**
[Shell Format Extension](https://marketplace.visualstudio.com/items?itemName=foxundermoon.shell-format)
This extension automatically formats your shell scripts according to best practices, ensuring clean, readable code.
### Script Modification
When creating a new script, you’ll need to adjust the call in the **`AppName.sh`** script. Specifically, the URL used in the following command must point to your **fork** of the repository, not the main `community-scripts/ProxmoxVE` URL:
```bash ```bash
bash -c "$(wget -qLO - https://github.com/YOUR_FORK_URL/raw/main/ct/AppName.sh)" source /dev/stdin <<< "$FUNCTIONS_FILE_PATH"
color
verb_ip6
catch_errors
setting_up_container
network_check
update_os
```
### 3. Standard Dependencies
Common base dependencies should be installed first:
```bash
msg_info "Installing Dependencies"
$STD apt-get install -y curl sudo mc
msg_ok "Installed Dependencies"
```
### 4. File Writing Conventions
#### Writing Config Files
Use heredoc (`cat <<EOF`) for writing configuration files:
```bash
cat <<EOF >/etc/systemd/system/service.service
[Unit]
Description=Service Description
After=network.target
[Service]
Type=simple
ExecStart=/path/to/executable
Restart=always
[Install]
WantedBy=multi-user.target
EOF
```
#### Writing Environment Files
Use heredoc for environment files, with proper quoting:
```bash
cat <<EOF >/path/to/.env
VARIABLE="value"
PORT=3000
DB_NAME="${DB_NAME}"
EOF
```
### 5. Service Management
Standard way to enable and start services:
```bash
systemctl enable -q --now service.service
```
### 6. Cleanup Section
Every script should end with cleanup:
```bash
msg_info "Cleaning up"
$STD apt-get -y autoremove
$STD apt-get -y autoclean
msg_ok "Cleaned"
```
### 7. Progress Messages
Use standard message functions for consistent output:
```bash
msg_info "Starting task"
$STD some_command
msg_ok "Task completed"
```
### 8. Version Tracking
When installing specific versions, store the version number:
```bash
echo "${RELEASE}" >"/opt/${APPLICATION}_version.txt"
```
### 9. Credentials Management
Store credentials in a consistent location:
```bash
{
echo "Application-Credentials"
echo "Username: $USERNAME"
echo "Password: $PASSWORD"
} >> ~/application.creds
```
### 10. Directory Structure
Use consistent paths for applications:
- Application files: `/opt/application_name/`
- Configuration files: `/etc/application_name/`
- Data files: `/var/lib/application_name/`
### 11. Error Handling
Use the standard error handling function:
```bash
catch_errors
```
### 12. Final Setup
Every script should end with:
```bash
motd_ssh
customize
```
---
## Best Practices
1. Use `$STD` for commands that should have their output suppressed.
2. Use consistent variable naming (uppercase for global variables).
3. Always quote variables that might contain spaces.
4. Use `-q` flag for quiet operation where available.
5. Use consistent indentation (2 spaces).
6. Include cleanup sections to remove temporary files and packages.
7. Use descriptive message strings in msg_info/msg_ok functions.
---
## Building Your Own Scripts
The best way to build your own scripts is to start with [our template script](https://github.com/community-scripts/ProxmoxVE/blob/main/docs/templates/example-install.sh) and then modify it to your needs.
---
## Contribution Process
### 1. Fork the Repository
Fork the repository to your own GitHub account to start contributing.
### 2. Clone the Forked Repository
Clone your fork to your local machine using:
```bash
git clone https://github.com/YOUR_USERNAME/community-scripts.git
```
### 3. Create a New Branch
Before making changes, create a new branch for your feature or fix:
```bash
git checkout -b your-feature-branch
```
### 4. Commit Your Changes
Once you’ve made the necessary changes, commit them:
```bash
git commit -m "Your commit message"
```
### 5. Push to Your Fork
Push the changes to your forked repository:
```bash
git push origin your-feature-branch
```
### 6. Create a Pull Request
Open a pull request from your feature branch to the `main` branch of the original repository. Please ensure that your pull request follows the formatting and guidelines mentioned above.
---
## Wiki Pages
- [Contributing](https://github.com/community-scripts/ProxmoxVE/wiki/Contributing)
- [Installation Guide](https://github.com/community-scripts/ProxmoxVE/wiki/Installation-Guide)
- [Script Templates](https://github.com/community-scripts/ProxmoxVE/wiki/Script-Templates)