Enable Discovery debug logging for production troubleshooting
- Add DISCOVERY_LOG_LEVEL=debug - Add DISCOVERY_SHOW_PROGRESS=true - Temporary changes for debugging InitializerProcessor fixes on production
This commit is contained in:
598
docs/contributing/code-style.md
Normal file
598
docs/contributing/code-style.md
Normal file
@@ -0,0 +1,598 @@
|
||||
# Coding Standards
|
||||
|
||||
Diese Dokumentation beschreibt die Coding Standards, die bei der Entwicklung des Frameworks eingehalten werden sollten. Die Einhaltung dieser Standards gewährleistet einen konsistenten Codestil im gesamten Projekt und erleichtert die Zusammenarbeit zwischen Entwicklern.
|
||||
|
||||
## PHP-Standards
|
||||
|
||||
### PSR-Standards
|
||||
|
||||
Das Framework folgt den [PHP Standards Recommendations (PSR)](https://www.php-fig.org/psr/) des PHP Framework Interop Group (PHP-FIG):
|
||||
|
||||
- [PSR-1: Basic Coding Standard](https://www.php-fig.org/psr/psr-1/)
|
||||
- [PSR-2: Coding Style Guide](https://www.php-fig.org/psr/psr-2/) und [PSR-12: Extended Coding Style](https://www.php-fig.org/psr/psr-12/) (ersetzt PSR-2)
|
||||
- [PSR-4: Autoloading Standard](https://www.php-fig.org/psr/psr-4/)
|
||||
|
||||
### Allgemeine Richtlinien
|
||||
|
||||
#### Dateien
|
||||
|
||||
- Dateien MÜSSEN die UTF-8-Kodierung ohne BOM verwenden.
|
||||
- Dateien SOLLTEN entweder Deklarationen (Klassen, Funktionen, Konstanten) ODER Nebeneffekte (z.B. Ausgaben, Änderungen an .ini-Einstellungen) enthalten, aber NICHT beides.
|
||||
- Dateinamen MÜSSEN `PascalCase` für Klassen verwenden (z.B. `UserController.php`).
|
||||
- Alle PHP-Dateien MÜSSEN mit einer einzelnen leeren Zeile enden.
|
||||
|
||||
#### PHP-Tags
|
||||
|
||||
- PHP-Code MUSS die langen Tags `<?php ?>` oder die kurzen Echo-Tags `<?= ?>` verwenden.
|
||||
- Die schließenden Tags `?>` SOLLTEN bei Dateien, die nur PHP enthalten, weggelassen werden.
|
||||
|
||||
#### Zeichenkodierung und Zeilenumbrüche
|
||||
|
||||
- Der Code MUSS UTF-8 ohne BOM verwenden.
|
||||
- Zeilenumbrüche MÜSSEN im Unix-Format (LF) sein.
|
||||
|
||||
### Namenskonventionen
|
||||
|
||||
#### Namespaces
|
||||
|
||||
- Namespaces MÜSSEN `PascalCase` verwenden.
|
||||
- Der Basis-Namespace für das Framework ist `App\Framework`.
|
||||
- Der Basis-Namespace für anwendungsspezifischen Code ist `App\Application`.
|
||||
|
||||
```php
|
||||
namespace App\Framework\Http;
|
||||
namespace App\Application\Controllers;
|
||||
```
|
||||
|
||||
#### Klassen
|
||||
|
||||
- Klassennamen MÜSSEN `PascalCase` verwenden.
|
||||
- Schnittstellen MÜSSEN mit dem Suffix `Interface` enden.
|
||||
- Abstrakte Klassen SOLLTEN mit dem Präfix `Abstract` beginnen.
|
||||
- Traits SOLLTEN mit dem Suffix `Trait` enden.
|
||||
|
||||
```php
|
||||
class UserController
|
||||
interface RepositoryInterface
|
||||
abstract class AbstractController
|
||||
trait LoggableTrait
|
||||
```
|
||||
|
||||
#### Methoden und Funktionen
|
||||
|
||||
- Methoden- und Funktionsnamen MÜSSEN `camelCase` verwenden.
|
||||
- Methoden SOLLTEN Verben sein, die ihre Aktion beschreiben.
|
||||
|
||||
```php
|
||||
public function getUserById(int $id): ?User
|
||||
public function createUser(array $data): User
|
||||
public function updateUserProfile(User $user, array $data): bool
|
||||
```
|
||||
|
||||
#### Eigenschaften und Variablen
|
||||
|
||||
- Eigenschaften und Variablen MÜSSEN `camelCase` verwenden.
|
||||
- Private und geschützte Eigenschaften SOLLTEN NICHT mit einem Unterstrich beginnen.
|
||||
|
||||
```php
|
||||
private string $firstName;
|
||||
protected int $itemCount;
|
||||
public bool $isActive;
|
||||
```
|
||||
|
||||
#### Konstanten
|
||||
|
||||
- Klassenkonstanten MÜSSEN in `UPPER_CASE` mit Unterstrichen als Trennzeichen definiert werden.
|
||||
|
||||
```php
|
||||
public const MAX_ATTEMPTS = 5;
|
||||
private const DEFAULT_TIMEOUT = 30;
|
||||
```
|
||||
|
||||
#### Enums
|
||||
|
||||
- Enum-Namen MÜSSEN `PascalCase` verwenden.
|
||||
- Enum-Werte MÜSSEN `UPPER_CASE` mit Unterstrichen als Trennzeichen verwenden.
|
||||
|
||||
```php
|
||||
enum HttpMethod
|
||||
{
|
||||
case GET;
|
||||
case POST;
|
||||
case PUT;
|
||||
case DELETE;
|
||||
}
|
||||
|
||||
enum LogLevel: string
|
||||
{
|
||||
case DEBUG = 'debug';
|
||||
case INFO = 'info';
|
||||
case WARNING = 'warning';
|
||||
case ERROR = 'error';
|
||||
}
|
||||
```
|
||||
|
||||
### Codestruktur
|
||||
|
||||
#### Klassen
|
||||
|
||||
- Jede Klasse MUSS in einer eigenen Datei definiert werden.
|
||||
- Die Struktur einer Klasse SOLLTE wie folgt sein:
|
||||
1. Namespace-Deklaration
|
||||
2. Verwendete Imports (alphabetisch sortiert)
|
||||
3. Klassendokumentation (PHPDoc)
|
||||
4. Klassendeklaration
|
||||
5. Konstanten (öffentlich, geschützt, privat)
|
||||
6. Eigenschaften (öffentlich, geschützt, privat)
|
||||
7. Konstruktor und Destruktor
|
||||
8. Öffentliche Methoden
|
||||
9. Geschützte Methoden
|
||||
10. Private Methoden
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
namespace App\Framework\Database;
|
||||
|
||||
use App\Framework\Contracts\ConnectionInterface;
|
||||
use App\Framework\Exceptions\DatabaseException;
|
||||
|
||||
/**
|
||||
* Database connection manager.
|
||||
*/
|
||||
class Connection implements ConnectionInterface
|
||||
{
|
||||
/**
|
||||
* Default connection timeout in seconds.
|
||||
*/
|
||||
public const DEFAULT_TIMEOUT = 30;
|
||||
|
||||
/**
|
||||
* The active PDO connection.
|
||||
*/
|
||||
private ?\PDO $pdo = null;
|
||||
|
||||
/**
|
||||
* The database configuration.
|
||||
*/
|
||||
private array $config;
|
||||
|
||||
/**
|
||||
* Create a new database connection instance.
|
||||
*/
|
||||
public function __construct(array $config)
|
||||
{
|
||||
$this->config = $config;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the PDO connection.
|
||||
*/
|
||||
public function getPdo(): \PDO
|
||||
{
|
||||
if ($this->pdo === null) {
|
||||
$this->connect();
|
||||
}
|
||||
|
||||
return $this->pdo;
|
||||
}
|
||||
|
||||
/**
|
||||
* Establish a database connection.
|
||||
*/
|
||||
protected function connect(): void
|
||||
{
|
||||
// Implementation...
|
||||
}
|
||||
|
||||
/**
|
||||
* Build the DSN string.
|
||||
*/
|
||||
private function buildDsn(): string
|
||||
{
|
||||
// Implementation...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Methoden
|
||||
|
||||
- Methoden SOLLTEN eine einzige Verantwortung haben (Single Responsibility Principle).
|
||||
- Methoden SOLLTEN kurz sein und eine Sache gut machen.
|
||||
- Methoden SOLLTEN früh zurückkehren, um die Verschachtelungstiefe zu reduzieren.
|
||||
|
||||
```php
|
||||
// Gut
|
||||
public function getUserById(int $id): ?User
|
||||
{
|
||||
if ($id <= 0) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return $this->userRepository->find($id);
|
||||
}
|
||||
|
||||
// Schlecht
|
||||
public function getUserById(int $id): ?User
|
||||
{
|
||||
if ($id > 0) {
|
||||
$user = $this->userRepository->find($id);
|
||||
if ($user !== null) {
|
||||
return $user;
|
||||
} else {
|
||||
return null;
|
||||
}
|
||||
} else {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Typisierung
|
||||
|
||||
- Der Code MUSS strikte Typisierung verwenden.
|
||||
- Jede Datei SOLLTE mit `declare(strict_types=1);` beginnen.
|
||||
- Methoden und Funktionen MÜSSEN Typdeklarationen für Parameter und Rückgabewerte verwenden.
|
||||
- Eigenschaften MÜSSEN Typdeklarationen verwenden.
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Framework\Http;
|
||||
|
||||
class Request
|
||||
{
|
||||
private array $query;
|
||||
private array $request;
|
||||
|
||||
public function __construct(array $query, array $request)
|
||||
{
|
||||
$this->query = $query;
|
||||
$this->request = $request;
|
||||
}
|
||||
|
||||
public function query(string $key, mixed $default = null): mixed
|
||||
{
|
||||
return $this->query[$key] ?? $default;
|
||||
}
|
||||
|
||||
public function input(string $key, mixed $default = null): mixed
|
||||
{
|
||||
return $this->request[$key] ?? $default;
|
||||
}
|
||||
|
||||
public function has(string $key): bool
|
||||
{
|
||||
return isset($this->request[$key]);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Dokumentation
|
||||
|
||||
- Alle Klassen, Methoden, Eigenschaften und Konstanten MÜSSEN mit PHPDoc-Kommentaren dokumentiert werden.
|
||||
- PHPDoc-Kommentare MÜSSEN eine Beschreibung und alle relevanten Tags enthalten.
|
||||
- Komplexe Codeabschnitte SOLLTEN mit Inline-Kommentaren erklärt werden.
|
||||
|
||||
```php
|
||||
/**
|
||||
* Represents an HTTP request.
|
||||
*/
|
||||
class Request
|
||||
{
|
||||
/**
|
||||
* The query parameters.
|
||||
*
|
||||
* @var array<string, mixed>
|
||||
*/
|
||||
private array $query;
|
||||
|
||||
/**
|
||||
* Get a query parameter.
|
||||
*
|
||||
* @param string $key The parameter key
|
||||
* @param mixed $default The default value if the parameter does not exist
|
||||
*
|
||||
* @return mixed The parameter value or the default value
|
||||
*/
|
||||
public function query(string $key, mixed $default = null): mixed
|
||||
{
|
||||
return $this->query[$key] ?? $default;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Fehlerbehandlung
|
||||
|
||||
- Exceptions SOLLTEN für außergewöhnliche Bedingungen verwendet werden.
|
||||
- Benutzerdefinierte Exceptions SOLLTEN von einer Basis-Exception-Klasse erben.
|
||||
- Exception-Nachrichten SOLLTEN klar und informativ sein.
|
||||
|
||||
```php
|
||||
// Definieren einer benutzerdefinierten Exception
|
||||
class DatabaseException extends \RuntimeException
|
||||
{
|
||||
// ...
|
||||
}
|
||||
|
||||
// Werfen einer Exception
|
||||
if (!$this->isConnected()) {
|
||||
throw new DatabaseException('Database connection failed: ' . $this->getLastError());
|
||||
}
|
||||
|
||||
// Fangen einer Exception
|
||||
try {
|
||||
$user = $this->userRepository->find($id);
|
||||
} catch (DatabaseException $e) {
|
||||
$this->logger->error('Database error: ' . $e->getMessage());
|
||||
throw new ServiceException('Could not retrieve user data', 0, $e);
|
||||
}
|
||||
```
|
||||
|
||||
## JavaScript-Standards
|
||||
|
||||
### Allgemeine Richtlinien
|
||||
|
||||
- JavaScript-Code SOLLTE [ESLint](https://eslint.org/) mit der Konfiguration des Projekts verwenden.
|
||||
- ES6+ Features SOLLTEN verwendet werden.
|
||||
- Semicolons MÜSSEN verwendet werden.
|
||||
|
||||
### Namenskonventionen
|
||||
|
||||
- Variablen und Funktionen MÜSSEN `camelCase` verwenden.
|
||||
- Klassen MÜSSEN `PascalCase` verwenden.
|
||||
- Konstanten MÜSSEN `UPPER_CASE` mit Unterstrichen als Trennzeichen verwenden.
|
||||
- Private Eigenschaften und Methoden SOLLTEN mit einem Unterstrich beginnen.
|
||||
|
||||
```javascript
|
||||
// Variablen
|
||||
const maxItems = 10;
|
||||
let currentIndex = 0;
|
||||
|
||||
// Konstanten
|
||||
const MAX_RETRY_COUNT = 3;
|
||||
const API_BASE_URL = 'https://api.example.com';
|
||||
|
||||
// Funktionen
|
||||
function getUserData(userId) {
|
||||
// ...
|
||||
}
|
||||
|
||||
// Klassen
|
||||
class UserService {
|
||||
constructor(apiClient) {
|
||||
this._apiClient = apiClient;
|
||||
}
|
||||
|
||||
async getUser(id) {
|
||||
return this._apiClient.get(`/users/${id}`);
|
||||
}
|
||||
|
||||
_handleError(error) {
|
||||
console.error('API error:', error);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Codestruktur
|
||||
|
||||
- Jede Datei SOLLTE einen einzelnen Export haben.
|
||||
- Imports SOLLTEN am Anfang der Datei stehen und nach Typ gruppiert werden.
|
||||
- Funktionen SOLLTEN kurz sein und eine Sache gut machen.
|
||||
|
||||
```javascript
|
||||
// Imports
|
||||
import React, { useState, useEffect } from 'react';
|
||||
import PropTypes from 'prop-types';
|
||||
|
||||
// Eigene Imports
|
||||
import { UserService } from '../services/UserService';
|
||||
import { ErrorBoundary } from '../components/ErrorBoundary';
|
||||
|
||||
// Komponente
|
||||
function UserProfile({ userId }) {
|
||||
const [user, setUser] = useState(null);
|
||||
const [loading, setLoading] = useState(true);
|
||||
const [error, setError] = useState(null);
|
||||
|
||||
useEffect(() => {
|
||||
const fetchUser = async () => {
|
||||
try {
|
||||
setLoading(true);
|
||||
const userService = new UserService();
|
||||
const userData = await userService.getUser(userId);
|
||||
setUser(userData);
|
||||
} catch (err) {
|
||||
setError(err.message);
|
||||
} finally {
|
||||
setLoading(false);
|
||||
}
|
||||
};
|
||||
|
||||
fetchUser();
|
||||
}, [userId]);
|
||||
|
||||
if (loading) {
|
||||
return <div>Loading...</div>;
|
||||
}
|
||||
|
||||
if (error) {
|
||||
return <div>Error: {error}</div>;
|
||||
}
|
||||
|
||||
return (
|
||||
<div>
|
||||
<h1>{user.name}</h1>
|
||||
<p>{user.email}</p>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
UserProfile.propTypes = {
|
||||
userId: PropTypes.string.isRequired
|
||||
};
|
||||
|
||||
export default UserProfile;
|
||||
```
|
||||
|
||||
## CSS-Standards
|
||||
|
||||
### Allgemeine Richtlinien
|
||||
|
||||
- CSS-Code SOLLTE [Stylelint](https://stylelint.io/) mit der Konfiguration des Projekts verwenden.
|
||||
- CSS-Präprozessoren wie SASS oder LESS KÖNNEN verwendet werden.
|
||||
- CSS-Klassen SOLLTEN nach dem BEM-Muster (Block, Element, Modifier) benannt werden.
|
||||
|
||||
### Namenskonventionen
|
||||
|
||||
- CSS-Klassen MÜSSEN `kebab-case` verwenden.
|
||||
- BEM-Notation: `.block__element--modifier`
|
||||
|
||||
```css
|
||||
/* Block */
|
||||
.user-card {
|
||||
background-color: #fff;
|
||||
border-radius: 4px;
|
||||
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
|
||||
padding: 16px;
|
||||
}
|
||||
|
||||
/* Element */
|
||||
.user-card__avatar {
|
||||
border-radius: 50%;
|
||||
height: 64px;
|
||||
width: 64px;
|
||||
}
|
||||
|
||||
/* Element */
|
||||
.user-card__name {
|
||||
font-size: 18px;
|
||||
font-weight: bold;
|
||||
margin-top: 8px;
|
||||
}
|
||||
|
||||
/* Modifier */
|
||||
.user-card--premium {
|
||||
background-color: #f8f8f8;
|
||||
border: 1px solid #ddd;
|
||||
}
|
||||
```
|
||||
|
||||
### Codestruktur
|
||||
|
||||
- CSS-Regeln SOLLTEN nach Komponenten organisiert werden.
|
||||
- Medienabfragen SOLLTEN am Ende jeder Komponente stehen.
|
||||
- Vendor-Präfixe SOLLTEN automatisch mit Tools wie Autoprefixer hinzugefügt werden.
|
||||
|
||||
```css
|
||||
/* Komponente */
|
||||
.button {
|
||||
background-color: #007bff;
|
||||
border: none;
|
||||
border-radius: 4px;
|
||||
color: #fff;
|
||||
cursor: pointer;
|
||||
font-size: 16px;
|
||||
padding: 8px 16px;
|
||||
transition: background-color 0.2s;
|
||||
}
|
||||
|
||||
.button:hover {
|
||||
background-color: #0069d9;
|
||||
}
|
||||
|
||||
.button:focus {
|
||||
outline: none;
|
||||
box-shadow: 0 0 0 3px rgba(0, 123, 255, 0.25);
|
||||
}
|
||||
|
||||
.button--secondary {
|
||||
background-color: #6c757d;
|
||||
}
|
||||
|
||||
.button--secondary:hover {
|
||||
background-color: #5a6268;
|
||||
}
|
||||
|
||||
/* Medienabfragen */
|
||||
@media (max-width: 768px) {
|
||||
.button {
|
||||
font-size: 14px;
|
||||
padding: 6px 12px;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Tools und Automatisierung
|
||||
|
||||
### Code-Linting
|
||||
|
||||
Das Projekt verwendet verschiedene Linting-Tools, um die Einhaltung der Coding Standards zu gewährleisten:
|
||||
|
||||
- [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) für PHP
|
||||
- [ESLint](https://eslint.org/) für JavaScript
|
||||
- [Stylelint](https://stylelint.io/) für CSS
|
||||
|
||||
### Automatische Formatierung
|
||||
|
||||
Das Projekt unterstützt automatische Codeformatierung mit:
|
||||
|
||||
- [PHP-CS-Fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer) für PHP
|
||||
- [Prettier](https://prettier.io/) für JavaScript und CSS
|
||||
|
||||
### Verwendung der Tools
|
||||
|
||||
#### PHP_CodeSniffer
|
||||
|
||||
```bash
|
||||
# Überprüfen des Codes
|
||||
vendor/bin/phpcs src tests
|
||||
|
||||
# Automatisches Beheben von Problemen
|
||||
vendor/bin/phpcbf src tests
|
||||
```
|
||||
|
||||
#### PHP-CS-Fixer
|
||||
|
||||
```bash
|
||||
# Überprüfen des Codes
|
||||
vendor/bin/php-cs-fixer fix --dry-run --diff src
|
||||
|
||||
# Automatisches Beheben von Problemen
|
||||
vendor/bin/php-cs-fixer fix src
|
||||
```
|
||||
|
||||
#### ESLint
|
||||
|
||||
```bash
|
||||
# Überprüfen des Codes
|
||||
npm run lint:js
|
||||
|
||||
# Automatisches Beheben von Problemen
|
||||
npm run lint:js:fix
|
||||
```
|
||||
|
||||
#### Stylelint
|
||||
|
||||
```bash
|
||||
# Überprüfen des Codes
|
||||
npm run lint:css
|
||||
|
||||
# Automatisches Beheben von Problemen
|
||||
npm run lint:css:fix
|
||||
```
|
||||
|
||||
#### Prettier
|
||||
|
||||
```bash
|
||||
# Formatieren von JavaScript und CSS
|
||||
npm run format
|
||||
```
|
||||
|
||||
## Weitere Informationen
|
||||
|
||||
- [Pull Request-Anleitung](pull-requests.md): Erfahren Sie, wie Sie Pull Requests erstellen und überprüfen.
|
||||
- [Dokumentations-Anleitung](documentation.md): Erfahren Sie, wie Sie zur Dokumentation beitragen können.
|
||||
- [Architekturübersicht](../architecture/overview.md): Überblick über die Architektur des Frameworks.
|
||||
345
docs/contributing/documentation.md
Normal file
345
docs/contributing/documentation.md
Normal file
@@ -0,0 +1,345 @@
|
||||
# Dokumentations-Anleitung
|
||||
|
||||
Diese Anleitung beschreibt, wie Sie zur Dokumentation des Frameworks beitragen können. Eine gute Dokumentation ist entscheidend für die Benutzerfreundlichkeit und Wartbarkeit des Frameworks.
|
||||
|
||||
## Überblick über die Dokumentationsstruktur
|
||||
|
||||
Die Dokumentation des Frameworks ist in mehrere Bereiche unterteilt:
|
||||
|
||||
```
|
||||
docs/
|
||||
├── README.md # Übersicht und Navigationshilfe
|
||||
├── getting-started/ # Einstiegsdokumentation
|
||||
│ ├── installation.md # Installationsanleitung
|
||||
│ ├── configuration.md # Konfigurationsanleitung
|
||||
│ └── first-steps.md # Erste Schritte mit dem Framework
|
||||
├── architecture/ # Architektur-Dokumentation
|
||||
│ ├── overview.md # Architekturübersicht
|
||||
│ ├── components.md # Hauptkomponenten
|
||||
│ └── patterns.md # Verwendete Entwurfsmuster
|
||||
├── components/ # Komponentendokumentation
|
||||
│ ├── analytics/ # Analytics-Komponente
|
||||
│ │ ├── index.md # Übersicht
|
||||
│ │ ├── configuration.md # Konfiguration
|
||||
│ │ └── examples.md # Beispiele
|
||||
│ ├── validation/ # Validierungs-Komponente
|
||||
│ │ ├── index.md # Übersicht
|
||||
│ │ ├── rules.md # Validierungsregeln
|
||||
│ │ └── examples.md # Beispiele
|
||||
│ ├── security/ # Sicherheits-Komponente
|
||||
│ │ ├── index.md # Übersicht
|
||||
│ │ ├── csrf-protection.md # CSRF-Schutz im Detail
|
||||
│ │ ├── security-headers.md # Security Headers und CSP
|
||||
│ │ └── request-signing.md # Request Signing API
|
||||
│ ├── waf/ # WAF-Komponente
|
||||
│ │ ├── index.md # Übersicht
|
||||
│ │ ├── machine-learning.md # ML-Funktionalität
|
||||
│ │ └── configuration.md # Konfiguration
|
||||
│ └── ... # Weitere Komponenten
|
||||
├── guides/ # Entwickleranleitungen
|
||||
│ ├── routing.md # Routing-Anleitung
|
||||
│ ├── controllers.md # Controller-Anleitung
|
||||
│ ├── validation.md # Validierungs-Anleitung
|
||||
│ ├── security.md # Sicherheits-Anleitung
|
||||
│ └── ... # Weitere Anleitungen
|
||||
├── api/ # API-Dokumentation
|
||||
│ ├── index.md # API-Übersicht
|
||||
│ └── ... # Generierte API-Docs
|
||||
├── contributing/ # Beitragsrichtlinien
|
||||
│ ├── code-style.md # Coding-Standards
|
||||
│ ├── pull-requests.md # PR-Prozess
|
||||
│ └── documentation.md # Dokumentationsrichtlinien
|
||||
└── roadmap/ # Projektplanung
|
||||
├── features.md # Feature-Tracking
|
||||
├── tasks.md # Task-Tracking
|
||||
└── milestones.md # Meilensteine
|
||||
```
|
||||
|
||||
## Dokumentationsstandards
|
||||
|
||||
### Markdown-Format
|
||||
|
||||
Die gesamte Dokumentation wird in Markdown geschrieben. Hier sind die grundlegenden Formatierungsregeln:
|
||||
|
||||
#### Überschriften
|
||||
|
||||
Verwenden Sie `#` für Überschriften, mit einer Hierarchie von `#` (Hauptüberschrift) bis `######` (Überschrift der sechsten Ebene):
|
||||
|
||||
```markdown
|
||||
# Hauptüberschrift (H1)
|
||||
## Überschrift der zweiten Ebene (H2)
|
||||
### Überschrift der dritten Ebene (H3)
|
||||
#### Überschrift der vierten Ebene (H4)
|
||||
##### Überschrift der fünften Ebene (H5)
|
||||
###### Überschrift der sechsten Ebene (H6)
|
||||
```
|
||||
|
||||
#### Textformatierung
|
||||
|
||||
```markdown
|
||||
*Kursiver Text* oder _Kursiver Text_
|
||||
**Fetter Text** oder __Fetter Text__
|
||||
***Fett und kursiv*** oder ___Fett und kursiv___
|
||||
~~Durchgestrichen~~
|
||||
```
|
||||
|
||||
#### Listen
|
||||
|
||||
Ungeordnete Listen:
|
||||
|
||||
```markdown
|
||||
- Element 1
|
||||
- Element 2
|
||||
- Unterelement 2.1
|
||||
- Unterelement 2.2
|
||||
- Element 3
|
||||
```
|
||||
|
||||
Geordnete Listen:
|
||||
|
||||
```markdown
|
||||
1. Erster Schritt
|
||||
2. Zweiter Schritt
|
||||
1. Unterschritt 2.1
|
||||
2. Unterschritt 2.2
|
||||
3. Dritter Schritt
|
||||
```
|
||||
|
||||
#### Links
|
||||
|
||||
```markdown
|
||||
[Link-Text](URL)
|
||||
[Link zu einer anderen Dokumentationsseite](../pfad/zur/datei.md)
|
||||
[Link zu einem Abschnitt in derselben Datei](#abschnitt-id)
|
||||
```
|
||||
|
||||
#### Bilder
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
#### Codeblöcke
|
||||
|
||||
Für Inline-Code:
|
||||
|
||||
```markdown
|
||||
`Inline-Code`
|
||||
```
|
||||
|
||||
Für Codeblöcke:
|
||||
|
||||
````markdown
|
||||
```php
|
||||
// PHP-Code hier
|
||||
$variable = 'Wert';
|
||||
echo $variable;
|
||||
```
|
||||
````
|
||||
|
||||
Unterstützte Sprachen für Syntax-Highlighting:
|
||||
- `php` für PHP-Code
|
||||
- `js` oder `javascript` für JavaScript-Code
|
||||
- `html` für HTML-Code
|
||||
- `css` für CSS-Code
|
||||
- `bash` oder `shell` für Shell-Befehle
|
||||
- `json` für JSON-Daten
|
||||
- `xml` für XML-Daten
|
||||
- `sql` für SQL-Abfragen
|
||||
|
||||
#### Tabellen
|
||||
|
||||
```markdown
|
||||
| Spalte 1 | Spalte 2 | Spalte 3 |
|
||||
|----------|----------|----------|
|
||||
| Zelle 1 | Zelle 2 | Zelle 3 |
|
||||
| Zelle 4 | Zelle 5 | Zelle 6 |
|
||||
```
|
||||
|
||||
#### Blockzitate
|
||||
|
||||
```markdown
|
||||
> Dies ist ein Blockzitat.
|
||||
> Es kann mehrere Zeilen umfassen.
|
||||
```
|
||||
|
||||
#### Horizontale Linien
|
||||
|
||||
```markdown
|
||||
---
|
||||
```
|
||||
|
||||
### Dokumentationsstruktur
|
||||
|
||||
Jede Dokumentationsdatei sollte die folgende Struktur haben:
|
||||
|
||||
1. **Hauptüberschrift**: Der Titel des Dokuments als H1-Überschrift (`#`).
|
||||
2. **Einführung**: Eine kurze Einführung, die den Zweck und Umfang des Dokuments beschreibt.
|
||||
3. **Hauptinhalt**: Der Hauptinhalt des Dokuments, organisiert in Abschnitte mit H2-Überschriften (`##`).
|
||||
4. **Beispiele**: Praktische Beispiele, die die Verwendung der beschriebenen Funktionalität demonstrieren.
|
||||
5. **Weitere Informationen**: Links zu verwandten Dokumenten oder externen Ressourcen.
|
||||
|
||||
### Schreibstil
|
||||
|
||||
- Verwenden Sie eine klare, präzise und konsistente Sprache.
|
||||
- Schreiben Sie in der zweiten Person ("Sie können..." statt "Man kann...").
|
||||
- Verwenden Sie die aktive Stimme statt der passiven Stimme.
|
||||
- Halten Sie Sätze und Absätze kurz und fokussiert.
|
||||
- Verwenden Sie Aufzählungslisten für Schritte oder Optionen.
|
||||
- Erklären Sie Fachbegriffe, wenn sie zum ersten Mal verwendet werden.
|
||||
- Vermeiden Sie Jargon und Abkürzungen, es sei denn, sie sind allgemein bekannt oder wurden erklärt.
|
||||
|
||||
### Beispiele
|
||||
|
||||
Gute Beispiele sind ein wesentlicher Bestandteil der Dokumentation. Jedes Beispiel sollte:
|
||||
|
||||
- Realistisch und praxisnah sein
|
||||
- Vollständig und funktionsfähig sein
|
||||
- Gut kommentiert sein, um zu erklären, was passiert
|
||||
- Die empfohlenen Praktiken und Coding-Standards befolgen
|
||||
|
||||
## Beitragen zur Dokumentation
|
||||
|
||||
### Neue Dokumentation erstellen
|
||||
|
||||
Wenn Sie neue Dokumentation erstellen möchten:
|
||||
|
||||
1. Identifizieren Sie den Bereich, in dem die Dokumentation benötigt wird.
|
||||
2. Erstellen Sie eine neue Markdown-Datei im entsprechenden Verzeichnis.
|
||||
3. Folgen Sie der oben beschriebenen Dokumentationsstruktur.
|
||||
4. Fügen Sie die neue Datei in die Navigation ein, indem Sie Links in verwandten Dokumenten hinzufügen.
|
||||
|
||||
### Bestehende Dokumentation aktualisieren
|
||||
|
||||
Wenn Sie bestehende Dokumentation aktualisieren möchten:
|
||||
|
||||
1. Identifizieren Sie die zu aktualisierende Datei.
|
||||
2. Nehmen Sie die erforderlichen Änderungen vor, wobei Sie die Dokumentationsstandards einhalten.
|
||||
3. Aktualisieren Sie alle Links oder Verweise, die durch Ihre Änderungen betroffen sein könnten.
|
||||
|
||||
### Pull Request-Prozess für Dokumentation
|
||||
|
||||
Der Prozess für das Einreichen von Dokumentationsänderungen ist derselbe wie für Code-Änderungen:
|
||||
|
||||
1. Erstellen Sie einen Feature-Branch für Ihre Änderungen.
|
||||
2. Nehmen Sie die Änderungen vor.
|
||||
3. Reichen Sie einen Pull Request ein.
|
||||
4. Reagieren Sie auf Feedback und nehmen Sie bei Bedarf weitere Änderungen vor.
|
||||
|
||||
Weitere Informationen finden Sie in der [Pull Request-Anleitung](pull-requests.md).
|
||||
|
||||
## Dokumentation generieren
|
||||
|
||||
### API-Dokumentation
|
||||
|
||||
Die API-Dokumentation wird automatisch aus dem Quellcode generiert. Um die API-Dokumentation zu generieren:
|
||||
|
||||
```bash
|
||||
php console.php docs:generate-api
|
||||
```
|
||||
|
||||
Dies generiert die API-Dokumentation im Verzeichnis `docs/api/`.
|
||||
|
||||
### Dokumentation lokal anzeigen
|
||||
|
||||
Um die Dokumentation lokal anzuzeigen, können Sie einen Markdown-Viewer oder einen lokalen Webserver verwenden:
|
||||
|
||||
```bash
|
||||
# Mit PHP-Webserver
|
||||
php -S localhost:8000 -t docs
|
||||
|
||||
# Mit Node.js und docsify
|
||||
npm install -g docsify-cli
|
||||
docsify serve docs
|
||||
```
|
||||
|
||||
## Dokumentations-Checkliste
|
||||
|
||||
Verwenden Sie diese Checkliste, um sicherzustellen, dass Ihre Dokumentation vollständig und von hoher Qualität ist:
|
||||
|
||||
- [ ] Die Dokumentation folgt der standardisierten Struktur.
|
||||
- [ ] Die Hauptüberschrift beschreibt klar den Inhalt des Dokuments.
|
||||
- [ ] Die Einführung erklärt den Zweck und Umfang des Dokuments.
|
||||
- [ ] Alle Fachbegriffe werden erklärt oder verlinkt.
|
||||
- [ ] Die Dokumentation enthält praktische Beispiele.
|
||||
- [ ] Die Beispiele sind vollständig, funktionsfähig und gut kommentiert.
|
||||
- [ ] Die Dokumentation enthält Links zu verwandten Dokumenten.
|
||||
- [ ] Die Dokumentation ist frei von Rechtschreib- und Grammatikfehlern.
|
||||
- [ ] Die Formatierung ist konsistent und folgt den Markdown-Standards.
|
||||
- [ ] Die Dokumentation ist aktuell und spiegelt den aktuellen Stand des Codes wider.
|
||||
|
||||
## Tipps für gute Dokumentation
|
||||
|
||||
### Benutzerorientierung
|
||||
|
||||
Denken Sie immer an die Benutzer Ihrer Dokumentation:
|
||||
|
||||
- Wer sind sie? (Anfänger, erfahrene Entwickler, Mitwirkende)
|
||||
- Was wollen sie erreichen?
|
||||
- Welche Vorkenntnisse haben sie?
|
||||
|
||||
Passen Sie Ihre Dokumentation entsprechend an.
|
||||
|
||||
### Klare Struktur
|
||||
|
||||
Eine klare Struktur hilft den Benutzern, die benötigten Informationen schnell zu finden:
|
||||
|
||||
- Verwenden Sie aussagekräftige Überschriften.
|
||||
- Gruppieren Sie verwandte Informationen.
|
||||
- Verwenden Sie Aufzählungslisten und Tabellen, um Informationen zu organisieren.
|
||||
- Fügen Sie ein Inhaltsverzeichnis für längere Dokumente hinzu.
|
||||
|
||||
### Visuelle Elemente
|
||||
|
||||
Visuelle Elemente können die Dokumentation verbessern:
|
||||
|
||||
- Verwenden Sie Diagramme, um komplexe Beziehungen zu erklären.
|
||||
- Fügen Sie Screenshots hinzu, um Benutzeroberflächen zu zeigen.
|
||||
- Verwenden Sie Codebeispiele, um Konzepte zu demonstrieren.
|
||||
|
||||
### Kontinuierliche Verbesserung
|
||||
|
||||
Dokumentation ist nie "fertig":
|
||||
|
||||
- Überprüfen Sie regelmäßig die Dokumentation auf Aktualität.
|
||||
- Berücksichtigen Sie Feedback von Benutzern.
|
||||
- Aktualisieren Sie die Dokumentation, wenn sich der Code ändert.
|
||||
|
||||
## Häufige Probleme und Lösungen
|
||||
|
||||
### Veraltete Dokumentation
|
||||
|
||||
Problem: Die Dokumentation spiegelt nicht den aktuellen Stand des Codes wider.
|
||||
|
||||
Lösung:
|
||||
- Überprüfen Sie die Dokumentation regelmäßig.
|
||||
- Aktualisieren Sie die Dokumentation als Teil des Entwicklungsprozesses.
|
||||
- Verwenden Sie automatisierte Tools, um Inkonsistenzen zu erkennen.
|
||||
|
||||
### Unvollständige Dokumentation
|
||||
|
||||
Problem: Die Dokumentation deckt nicht alle Aspekte der Funktionalität ab.
|
||||
|
||||
Lösung:
|
||||
- Identifizieren Sie fehlende Bereiche durch Benutzerfeedback.
|
||||
- Erstellen Sie eine Checkliste der zu dokumentierenden Funktionen.
|
||||
- Priorisieren Sie die Dokumentation basierend auf der Benutzerrelevanz.
|
||||
|
||||
### Unklare Dokumentation
|
||||
|
||||
Problem: Die Dokumentation ist schwer zu verstehen oder zu technisch.
|
||||
|
||||
Lösung:
|
||||
- Verwenden Sie einfache, klare Sprache.
|
||||
- Erklären Sie Fachbegriffe.
|
||||
- Fügen Sie Beispiele hinzu, um Konzepte zu verdeutlichen.
|
||||
- Lassen Sie die Dokumentation von jemandem überprüfen, der mit dem Thema nicht vertraut ist.
|
||||
|
||||
## Weitere Informationen
|
||||
|
||||
- [Markdown-Anleitung](https://www.markdownguide.org/): Eine umfassende Anleitung zu Markdown.
|
||||
- [Technisches Schreiben](https://developers.google.com/tech-writing): Google's Anleitung zum technischen Schreiben.
|
||||
- [Dokumentationstools](https://docusaurus.io/): Tools für die Erstellung und Verwaltung von Dokumentation.
|
||||
- [Coding Standards](code-style.md): Erfahren Sie mehr über die Coding Standards des Projekts.
|
||||
- [Pull Request-Anleitung](pull-requests.md): Erfahren Sie, wie Sie Pull Requests erstellen und überprüfen.
|
||||
- [Architekturübersicht](../architecture/overview.md): Überblick über die Architektur des Frameworks.
|
||||
334
docs/contributing/pull-requests.md
Normal file
334
docs/contributing/pull-requests.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# Pull Request-Anleitung
|
||||
|
||||
Diese Anleitung beschreibt den Prozess für das Erstellen, Überprüfen und Zusammenführen von Pull Requests im Framework-Projekt. Die Einhaltung dieser Richtlinien gewährleistet einen reibungslosen Entwicklungsprozess und eine hohe Codequalität.
|
||||
|
||||
## Überblick über den Pull Request-Prozess
|
||||
|
||||
Der Pull Request-Prozess besteht aus den folgenden Schritten:
|
||||
|
||||
1. **Vorbereitung**: Erstellen eines Issues und eines Feature-Branches
|
||||
2. **Entwicklung**: Implementieren der Änderungen und Schreiben von Tests
|
||||
3. **Einreichen**: Erstellen eines Pull Requests
|
||||
4. **Überprüfung**: Code-Review und Diskussion
|
||||
5. **Anpassung**: Vornehmen von Änderungen basierend auf dem Feedback
|
||||
6. **Zusammenführen**: Zusammenführen des Pull Requests in den Hauptbranch
|
||||
|
||||
## 1. Vorbereitung
|
||||
|
||||
### Issues erstellen
|
||||
|
||||
Bevor Sie mit der Arbeit an einer neuen Funktion oder Fehlerbehebung beginnen, sollten Sie sicherstellen, dass ein entsprechendes Issue existiert:
|
||||
|
||||
1. Überprüfen Sie die bestehenden Issues, um Duplikate zu vermeiden.
|
||||
2. Wenn kein passendes Issue existiert, erstellen Sie ein neues Issue mit einer klaren Beschreibung des Problems oder der Funktion.
|
||||
3. Warten Sie auf Feedback vom Kernteam, um sicherzustellen, dass Ihre geplante Änderung mit der Projektrichtung übereinstimmt.
|
||||
|
||||
### Feature-Branch erstellen
|
||||
|
||||
Sobald Sie ein Issue haben, an dem Sie arbeiten möchten, erstellen Sie einen Feature-Branch:
|
||||
|
||||
```bash
|
||||
# Aktualisieren Sie Ihren lokalen main-Branch
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
# Erstellen Sie einen Feature-Branch
|
||||
git checkout -b feature/issue-123-kurze-beschreibung
|
||||
```
|
||||
|
||||
Verwenden Sie eine konsistente Benennungskonvention für Branches:
|
||||
- `feature/issue-XXX-kurze-beschreibung` für neue Funktionen
|
||||
- `bugfix/issue-XXX-kurze-beschreibung` für Fehlerbehebungen
|
||||
- `refactor/issue-XXX-kurze-beschreibung` für Refactoring
|
||||
- `docs/issue-XXX-kurze-beschreibung` für Dokumentationsänderungen
|
||||
|
||||
## 2. Entwicklung
|
||||
|
||||
### Coding Standards
|
||||
|
||||
Stellen Sie sicher, dass Ihr Code den [Coding Standards](code-style.md) des Projekts entspricht. Verwenden Sie die bereitgestellten Linting-Tools, um die Einhaltung der Standards zu überprüfen:
|
||||
|
||||
```bash
|
||||
# PHP-Code überprüfen
|
||||
vendor/bin/phpcs src tests
|
||||
|
||||
# JavaScript-Code überprüfen
|
||||
npm run lint:js
|
||||
|
||||
# CSS-Code überprüfen
|
||||
npm run lint:css
|
||||
```
|
||||
|
||||
### Tests schreiben
|
||||
|
||||
Für jede Änderung sollten entsprechende Tests geschrieben werden:
|
||||
|
||||
- **Unit-Tests** für einzelne Klassen und Methoden
|
||||
- **Integrationstests** für die Interaktion zwischen Komponenten
|
||||
- **Funktionstests** für die Überprüfung von Benutzerszenarien
|
||||
|
||||
```bash
|
||||
# Tests ausführen
|
||||
vendor/bin/phpunit
|
||||
|
||||
# Spezifische Testdatei ausführen
|
||||
vendor/bin/phpunit tests/Unit/Framework/Http/RequestTest.php
|
||||
|
||||
# Tests mit Code-Coverage-Bericht ausführen
|
||||
vendor/bin/phpunit --coverage-html coverage
|
||||
```
|
||||
|
||||
### Commit-Richtlinien
|
||||
|
||||
Schreiben Sie klare und aussagekräftige Commit-Nachrichten, die den Zweck des Commits beschreiben:
|
||||
|
||||
```
|
||||
feat(component): Kurze Beschreibung der Änderung
|
||||
|
||||
Längere Beschreibung mit Details zur Änderung, Motivation und Kontext.
|
||||
Mehrere Zeilen sind erlaubt.
|
||||
|
||||
Fixes #123
|
||||
```
|
||||
|
||||
Verwenden Sie die folgenden Präfixe für Ihre Commit-Nachrichten:
|
||||
- `feat`: Neue Funktion
|
||||
- `fix`: Fehlerbehebung
|
||||
- `docs`: Dokumentationsänderungen
|
||||
- `style`: Formatierung, fehlende Semikolons usw. (keine Codeänderungen)
|
||||
- `refactor`: Code-Refactoring
|
||||
- `test`: Hinzufügen oder Korrigieren von Tests
|
||||
- `chore`: Änderungen an Build-Prozessen oder Hilfswerkzeugen
|
||||
|
||||
### Regelmäßiges Pushen
|
||||
|
||||
Pushen Sie Ihre Änderungen regelmäßig in Ihren Remote-Branch:
|
||||
|
||||
```bash
|
||||
git push origin feature/issue-123-kurze-beschreibung
|
||||
```
|
||||
|
||||
## 3. Einreichen
|
||||
|
||||
### Vorbereitung für den Pull Request
|
||||
|
||||
Bevor Sie einen Pull Request erstellen, stellen Sie sicher, dass:
|
||||
|
||||
1. Alle Tests erfolgreich durchlaufen werden.
|
||||
2. Der Code den Coding Standards entspricht.
|
||||
3. Die Dokumentation aktualisiert wurde (falls erforderlich).
|
||||
4. Der Branch auf dem neuesten Stand mit dem Hauptbranch ist.
|
||||
|
||||
```bash
|
||||
# Aktualisieren Sie Ihren Branch mit dem neuesten Stand des Hauptbranches
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout feature/issue-123-kurze-beschreibung
|
||||
git merge main
|
||||
git push origin feature/issue-123-kurze-beschreibung
|
||||
```
|
||||
|
||||
### Pull Request erstellen
|
||||
|
||||
Erstellen Sie einen Pull Request über die GitHub-Oberfläche:
|
||||
|
||||
1. Navigieren Sie zu Ihrem Branch auf GitHub.
|
||||
2. Klicken Sie auf "Compare & pull request".
|
||||
3. Füllen Sie die Pull Request-Vorlage aus:
|
||||
- Titel: Kurze Beschreibung der Änderung (max. 72 Zeichen)
|
||||
- Beschreibung: Detaillierte Beschreibung der Änderung, Motivation und Kontext
|
||||
- Referenzieren Sie das zugehörige Issue mit "Fixes #123" oder "Relates to #123"
|
||||
4. Klicken Sie auf "Create pull request".
|
||||
|
||||
### Pull Request-Vorlage
|
||||
|
||||
```markdown
|
||||
## Beschreibung
|
||||
|
||||
[Beschreiben Sie hier Ihre Änderungen und den Kontext]
|
||||
|
||||
## Motivation und Kontext
|
||||
|
||||
[Warum ist diese Änderung erforderlich? Welches Problem löst sie?]
|
||||
|
||||
## Art der Änderung
|
||||
|
||||
- [ ] Fehlerbehebung (nicht-breaking change, behebt ein Problem)
|
||||
- [ ] Neue Funktion (nicht-breaking change, fügt Funktionalität hinzu)
|
||||
- [ ] Breaking change (Fehlerbehebung oder Funktion, die zu Inkompatibilitäten führt)
|
||||
- [ ] Diese Änderung erfordert eine Dokumentationsaktualisierung
|
||||
|
||||
## Wie wurde getestet?
|
||||
|
||||
[Beschreiben Sie die Tests, die Sie durchgeführt haben, um Ihre Änderungen zu überprüfen]
|
||||
|
||||
## Checkliste:
|
||||
|
||||
- [ ] Mein Code folgt dem Codestil dieses Projekts
|
||||
- [ ] Ich habe Selbstüberprüfung meines Codes durchgeführt
|
||||
- [ ] Ich habe Kommentare zu meinem Code hinzugefügt, insbesondere in schwer verständlichen Bereichen
|
||||
- [ ] Ich habe entsprechende Änderungen an der Dokumentation vorgenommen
|
||||
- [ ] Meine Änderungen erzeugen keine neuen Warnungen
|
||||
- [ ] Ich habe Tests hinzugefügt, die meine Änderungen beweisen
|
||||
- [ ] Neue und bestehende Unit-Tests bestehen lokal mit meinen Änderungen
|
||||
- [ ] Alle abhängigen Änderungen wurden zusammengeführt und veröffentlicht
|
||||
|
||||
## Zugehörige Issues
|
||||
|
||||
[Verlinken Sie hier zugehörige Issues, z.B. "Fixes #123"]
|
||||
```
|
||||
|
||||
## 4. Überprüfung
|
||||
|
||||
### Code-Review-Prozess
|
||||
|
||||
Nach dem Erstellen eines Pull Requests wird er von mindestens einem Mitglied des Kernteams überprüft. Der Reviewer wird:
|
||||
|
||||
1. Den Code auf Einhaltung der Coding Standards überprüfen.
|
||||
2. Die Funktionalität und Korrektheit der Änderungen bewerten.
|
||||
3. Die Testabdeckung überprüfen.
|
||||
4. Feedback und Verbesserungsvorschläge geben.
|
||||
|
||||
### Automatisierte Checks
|
||||
|
||||
Jeder Pull Request durchläuft automatisierte Checks:
|
||||
|
||||
- **CI-Pipeline**: Führt Tests und Linting-Checks aus
|
||||
- **Code-Coverage**: Überprüft die Testabdeckung
|
||||
- **Dependency-Scanning**: Überprüft auf Sicherheitsprobleme in Abhängigkeiten
|
||||
|
||||
Alle automatisierten Checks müssen erfolgreich sein, bevor ein Pull Request zusammengeführt werden kann.
|
||||
|
||||
### Feedback erhalten und geben
|
||||
|
||||
Beim Geben und Erhalten von Feedback:
|
||||
|
||||
- Seien Sie respektvoll und konstruktiv.
|
||||
- Konzentrieren Sie sich auf den Code, nicht auf die Person.
|
||||
- Erklären Sie Ihre Gedanken und geben Sie Beispiele.
|
||||
- Stellen Sie Fragen, anstatt Annahmen zu treffen.
|
||||
|
||||
## 5. Anpassung
|
||||
|
||||
### Änderungen vornehmen
|
||||
|
||||
Basierend auf dem Feedback aus dem Code-Review können Sie Änderungen an Ihrem Branch vornehmen:
|
||||
|
||||
```bash
|
||||
# Änderungen vornehmen
|
||||
git add .
|
||||
git commit -m "fix: Adressieren von Feedback aus dem Code-Review"
|
||||
git push origin feature/issue-123-kurze-beschreibung
|
||||
```
|
||||
|
||||
Die neuen Commits werden automatisch zum Pull Request hinzugefügt.
|
||||
|
||||
### Konflikte lösen
|
||||
|
||||
Wenn Konflikte mit dem Hauptbranch auftreten, müssen Sie diese lösen:
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout feature/issue-123-kurze-beschreibung
|
||||
git merge main
|
||||
# Konflikte lösen
|
||||
git add .
|
||||
git commit -m "chore: Merge main und löse Konflikte"
|
||||
git push origin feature/issue-123-kurze-beschreibung
|
||||
```
|
||||
|
||||
## 6. Zusammenführen
|
||||
|
||||
### Anforderungen für das Zusammenführen
|
||||
|
||||
Bevor ein Pull Request zusammengeführt werden kann, muss er:
|
||||
|
||||
1. Von mindestens einem Mitglied des Kernteams genehmigt werden.
|
||||
2. Alle automatisierten Checks bestehen.
|
||||
3. Keine offenen Diskussionen oder Anfragen nach Änderungen haben.
|
||||
|
||||
### Zusammenführungsmethoden
|
||||
|
||||
Das Projekt verwendet verschiedene Zusammenführungsmethoden je nach Art der Änderung:
|
||||
|
||||
- **Squash and merge**: Für kleine Änderungen oder Fehlerbehebungen, um die Commit-Historie sauber zu halten.
|
||||
- **Merge commit**: Für größere Funktionen, bei denen die einzelnen Commits wichtig sind.
|
||||
- **Rebase and merge**: Für Änderungen, die eine lineare Historie erfordern.
|
||||
|
||||
Die bevorzugte Methode ist "Squash and merge", es sei denn, es gibt einen guten Grund für eine andere Methode.
|
||||
|
||||
### Nach dem Zusammenführen
|
||||
|
||||
Nach dem Zusammenführen eines Pull Requests:
|
||||
|
||||
1. Der Feature-Branch kann gelöscht werden.
|
||||
2. Das zugehörige Issue wird automatisch geschlossen (wenn "Fixes #123" verwendet wurde).
|
||||
3. Die Änderungen werden in der nächsten Version des Frameworks enthalten sein.
|
||||
|
||||
## Tipps für erfolgreiche Pull Requests
|
||||
|
||||
### Kleine, fokussierte Änderungen
|
||||
|
||||
Halten Sie Pull Requests klein und fokussiert auf eine einzelne Änderung. Dies erleichtert die Überprüfung und reduziert das Risiko von Konflikten.
|
||||
|
||||
### Klare Dokumentation
|
||||
|
||||
Dokumentieren Sie Ihre Änderungen gründlich, sowohl im Code als auch in der Pull Request-Beschreibung. Erklären Sie, warum die Änderung notwendig ist und wie sie implementiert wurde.
|
||||
|
||||
### Kommunikation
|
||||
|
||||
Kommunizieren Sie aktiv mit Reviewern und anderen Mitwirkenden. Beantworten Sie Fragen zeitnah und bitten Sie um Klärung, wenn etwas unklar ist.
|
||||
|
||||
### Geduld
|
||||
|
||||
Der Review-Prozess kann Zeit in Anspruch nehmen, besonders bei komplexen Änderungen. Haben Sie Geduld und nutzen Sie die Zeit, um Ihre Änderungen zu verbessern.
|
||||
|
||||
## Häufige Probleme und Lösungen
|
||||
|
||||
### Mein Branch ist veraltet
|
||||
|
||||
Wenn Ihr Branch veraltet ist und Konflikte mit dem Hauptbranch hat:
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout feature/issue-123-kurze-beschreibung
|
||||
git merge main
|
||||
# Konflikte lösen
|
||||
git add .
|
||||
git commit -m "chore: Merge main und löse Konflikte"
|
||||
git push origin feature/issue-123-kurze-beschreibung
|
||||
```
|
||||
|
||||
### Ich habe einen Fehler in meinem letzten Commit gemacht
|
||||
|
||||
Wenn Sie einen Fehler in Ihrem letzten Commit gemacht haben und ihn noch nicht gepusht haben:
|
||||
|
||||
```bash
|
||||
# Änderungen vornehmen
|
||||
git add .
|
||||
git commit --amend
|
||||
git push origin feature/issue-123-kurze-beschreibung --force
|
||||
```
|
||||
|
||||
**Hinweis**: Verwenden Sie `--force` mit Vorsicht, besonders wenn andere Personen an demselben Branch arbeiten.
|
||||
|
||||
### Ich möchte meine Commits aufräumen, bevor ich einen Pull Request erstelle
|
||||
|
||||
Wenn Sie Ihre Commits aufräumen möchten, bevor Sie einen Pull Request erstellen:
|
||||
|
||||
```bash
|
||||
# Interaktives Rebase für die letzten n Commits
|
||||
git rebase -i HEAD~n
|
||||
|
||||
# Pushen Sie die Änderungen
|
||||
git push origin feature/issue-123-kurze-beschreibung --force
|
||||
```
|
||||
|
||||
## Weitere Informationen
|
||||
|
||||
- [Coding Standards](code-style.md): Erfahren Sie mehr über die Coding Standards des Projekts.
|
||||
- [Dokumentations-Anleitung](documentation.md): Erfahren Sie, wie Sie zur Dokumentation beitragen können.
|
||||
- [GitHub Flow](https://guides.github.com/introduction/flow/): Eine leichtgewichtige, branchbasierte Workflow-Anleitung.
|
||||
- [Architekturübersicht](../architecture/overview.md): Überblick über die Architektur des Frameworks.
|
||||
Reference in New Issue
Block a user