This commit is contained in:
410
CONTRIBUTING.md
Normal file
410
CONTRIBUTING.md
Normal file
@@ -0,0 +1,410 @@
|
||||
# Contributing to Nextcloud Share
|
||||
|
||||
Thank you for your interest in contributing to Nextcloud Share! This document provides guidelines and workflows for contributing to the project.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Code of Conduct](#code-of-conduct)
|
||||
- [Getting Started](#getting-started)
|
||||
- [Git Workflow](#git-workflow)
|
||||
- [Development Setup](#development-setup)
|
||||
- [Making Changes](#making-changes)
|
||||
- [Submitting a Pull Request](#submitting-a-pull-request)
|
||||
- [Issue Guidelines](#issue-guidelines)
|
||||
- [Commit Message Guidelines](#commit-message-guidelines)
|
||||
|
||||
---
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
We expect all contributors to be respectful, inclusive, and professional. Please:
|
||||
|
||||
- Be welcoming to newcomers
|
||||
- Provide constructive feedback
|
||||
- Focus on what is best for the community
|
||||
- Show empathy towards other community members
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. **Fork the repository** on Gitea (if external contributor)
|
||||
2. **Clone your fork** locally:
|
||||
```bash
|
||||
git clone https://git.tomusan.com/maj/nextcloud-share.git
|
||||
cd nextcloud-share
|
||||
```
|
||||
3. **Add upstream remote** (if forked):
|
||||
```bash
|
||||
git remote add upstream https://git.tomusan.com/maj/nextcloud-share.git
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Git Workflow
|
||||
|
||||
This project uses the **git-flow** branching model. Understanding this workflow is essential for contributing.
|
||||
|
||||
### Branch Structure
|
||||
|
||||
#### `main` - Production Branch
|
||||
- **Purpose**: Contains production-ready, stable releases only
|
||||
- **Rules**:
|
||||
- Never commit directly to `main`
|
||||
- Only receives merges from `release/*` or `hotfix/*` branches
|
||||
- Every commit on `main` is tagged with a version number
|
||||
- Represents the current production state
|
||||
|
||||
#### `develop` - Integration Branch
|
||||
- **Purpose**: Integration branch where features come together
|
||||
- **Rules**:
|
||||
- Default branch for development
|
||||
- Never commit directly to `develop`
|
||||
- Receives merges from `feature/*` branches
|
||||
- Always contains the latest delivered development changes
|
||||
- Should always be in a working state
|
||||
|
||||
#### `feature/*` - Feature Branches
|
||||
- **Purpose**: Develop new features or enhancements
|
||||
- **Naming**: `feature/<issue-number>-<short-description>`
|
||||
- Example: `feature/8-webdav-client`
|
||||
- **Branch from**: `develop`
|
||||
- **Merge into**: `develop`
|
||||
- **Lifetime**: Deleted after merge
|
||||
|
||||
**Creating a feature branch**:
|
||||
```bash
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
git checkout -b feature/8-webdav-client
|
||||
```
|
||||
|
||||
**Merging a feature**:
|
||||
```bash
|
||||
git checkout develop
|
||||
git merge --no-ff feature/8-webdav-client
|
||||
git push origin develop
|
||||
git branch -d feature/8-webdav-client
|
||||
```
|
||||
|
||||
#### `release/*` - Release Preparation Branches
|
||||
- **Purpose**: Prepare for a new production release
|
||||
- **Naming**: `release/v<version>`
|
||||
- Example: `release/v0.1.0`
|
||||
- **Branch from**: `develop`
|
||||
- **Merge into**: `main` AND `develop`
|
||||
- **Lifetime**: Deleted after merge
|
||||
|
||||
**Creating a release branch**:
|
||||
```bash
|
||||
git checkout develop
|
||||
git checkout -b release/v0.1.0
|
||||
# Bump version numbers, update CHANGELOG, etc.
|
||||
```
|
||||
|
||||
**Finishing a release**:
|
||||
```bash
|
||||
# Merge to main
|
||||
git checkout main
|
||||
git merge --no-ff release/v0.1.0
|
||||
git tag -a v0.1.0 -m "Release version 0.1.0"
|
||||
git push origin main --tags
|
||||
|
||||
# Merge back to develop
|
||||
git checkout develop
|
||||
git merge --no-ff release/v0.1.0
|
||||
git push origin develop
|
||||
|
||||
# Delete release branch
|
||||
git branch -d release/v0.1.0
|
||||
```
|
||||
|
||||
#### `hotfix/*` - Emergency Fix Branches
|
||||
- **Purpose**: Quick fixes for critical production bugs
|
||||
- **Naming**: `hotfix/v<version>-<description>`
|
||||
- Example: `hotfix/v0.1.1-fix-crash`
|
||||
- **Branch from**: `main`
|
||||
- **Merge into**: `main` AND `develop`
|
||||
- **Lifetime**: Deleted after merge
|
||||
|
||||
**Creating a hotfix**:
|
||||
```bash
|
||||
git checkout main
|
||||
git checkout -b hotfix/v0.1.1-fix-crash
|
||||
# Make the fix
|
||||
```
|
||||
|
||||
**Finishing a hotfix**:
|
||||
```bash
|
||||
# Merge to main
|
||||
git checkout main
|
||||
git merge --no-ff hotfix/v0.1.1-fix-crash
|
||||
git tag -a v0.1.1 -m "Hotfix version 0.1.1"
|
||||
git push origin main --tags
|
||||
|
||||
# Merge to develop
|
||||
git checkout develop
|
||||
git merge --no-ff hotfix/v0.1.1-fix-crash
|
||||
git push origin develop
|
||||
|
||||
# Delete hotfix branch
|
||||
git branch -d hotfix/v0.1.1-fix-crash
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Podman** (preferred) or **Docker**
|
||||
- **Git**
|
||||
- **jq** (for config parsing)
|
||||
|
||||
### Configuration
|
||||
|
||||
1. **Copy the example config**:
|
||||
```bash
|
||||
cp config.example.json config.json
|
||||
```
|
||||
|
||||
2. **Edit `config.json`** with your Nextcloud test credentials:
|
||||
```json
|
||||
{
|
||||
"nextcloud": {
|
||||
"url": "https://cloud.tomusan.com",
|
||||
"username": "your-username",
|
||||
"password": "your-app-password"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Never commit `config.json`** - it's in `.gitignore`
|
||||
|
||||
### Building with Containers
|
||||
|
||||
All builds should be done inside containers to ensure consistency:
|
||||
|
||||
```bash
|
||||
# Build 3DS app (when available)
|
||||
podman build -f docker/devkitarm.Dockerfile -t nextcloud-share-3ds .
|
||||
podman run --rm -v ./:/project:z nextcloud-share-3ds make -C 3ds
|
||||
|
||||
# Build shared library (when available)
|
||||
podman build -f docker/builder.Dockerfile -t builder .
|
||||
podman run --rm -v ./:/project:z builder cmake -B build -S shared
|
||||
podman run --rm -v ./:/project:z builder cmake --build build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Making Changes
|
||||
|
||||
### 1. Find or Create an Issue
|
||||
|
||||
- Check [existing issues](https://git.tomusan.com/maj/nextcloud-share/issues)
|
||||
- Create a new issue if needed
|
||||
- Get issue number (e.g., `#42`)
|
||||
|
||||
### 2. Create a Feature Branch
|
||||
|
||||
```bash
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
git checkout -b feature/42-short-description
|
||||
```
|
||||
|
||||
### 3. Make Your Changes
|
||||
|
||||
- Write clean, maintainable code
|
||||
- Follow existing code style
|
||||
- Add tests for new functionality
|
||||
- Update documentation as needed
|
||||
- Test your changes thoroughly
|
||||
|
||||
### 4. Commit Your Changes
|
||||
|
||||
Follow the [commit message guidelines](#commit-message-guidelines):
|
||||
|
||||
```bash
|
||||
git add <files>
|
||||
git commit -m "feat: add WebDAV client implementation (#42)"
|
||||
```
|
||||
|
||||
### 5. Keep Your Branch Updated
|
||||
|
||||
```bash
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
git checkout feature/42-short-description
|
||||
git rebase develop
|
||||
```
|
||||
|
||||
### 6. Push Your Branch
|
||||
|
||||
```bash
|
||||
git push origin feature/42-short-description
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Submitting a Pull Request
|
||||
|
||||
1. **Push your feature branch** to the repository
|
||||
2. **Open a Pull Request** on Gitea:
|
||||
- Base: `develop`
|
||||
- Compare: `feature/42-short-description`
|
||||
3. **Fill out the PR template**:
|
||||
- Reference the issue number (e.g., "Closes #42")
|
||||
- Describe what changed and why
|
||||
- Add any testing notes
|
||||
4. **Wait for review**:
|
||||
- Address any feedback
|
||||
- Push additional commits if needed
|
||||
- CI must pass before merge
|
||||
|
||||
### PR Checklist
|
||||
|
||||
- [ ] Branch is up-to-date with `develop`
|
||||
- [ ] All tests pass locally
|
||||
- [ ] New tests added for new features
|
||||
- [ ] Documentation updated
|
||||
- [ ] Commit messages follow guidelines
|
||||
- [ ] CI pipeline passes
|
||||
- [ ] Code has been self-reviewed
|
||||
- [ ] No sensitive data (passwords, tokens) in commits
|
||||
|
||||
---
|
||||
|
||||
## Issue Guidelines
|
||||
|
||||
### Creating Issues
|
||||
|
||||
- **Use a clear, descriptive title**
|
||||
- **Provide context**: What are you trying to do?
|
||||
- **Include reproduction steps** for bugs
|
||||
- **Add relevant labels**: `bug`, `feature`, `platform:3ds`, etc.
|
||||
- **Reference related issues** if applicable
|
||||
|
||||
### Working on Issues
|
||||
|
||||
- **Comment on the issue** before starting work to avoid duplication
|
||||
- **Update the issue** with progress notes
|
||||
- **Link commits** to issues using `#<issue-number>` in commit messages
|
||||
- **Close issues** with "Closes #<number>" or "Fixes #<number>" in PR description
|
||||
|
||||
---
|
||||
|
||||
## Commit Message Guidelines
|
||||
|
||||
We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
|
||||
|
||||
### Format
|
||||
|
||||
```
|
||||
<type>(<scope>): <subject> (#<issue>)
|
||||
|
||||
<body>
|
||||
|
||||
<footer>
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
- **feat**: New feature
|
||||
- **fix**: Bug fix
|
||||
- **docs**: Documentation changes
|
||||
- **style**: Code style changes (formatting, no logic change)
|
||||
- **refactor**: Code refactoring
|
||||
- **test**: Adding or updating tests
|
||||
- **chore**: Maintenance tasks
|
||||
- **ci**: CI/CD changes
|
||||
- **perf**: Performance improvements
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Simple feature
|
||||
git commit -m "feat: add WebDAV client implementation (#8)"
|
||||
|
||||
# Bug fix
|
||||
git commit -m "fix: resolve memory leak in upload manager (#25)"
|
||||
|
||||
# With scope
|
||||
git commit -m "feat(3ds): implement SD card file browser (#16)"
|
||||
|
||||
# With body
|
||||
git commit -m "refactor: simplify authentication logic (#9)
|
||||
|
||||
The previous implementation had unnecessary complexity.
|
||||
This refactoring makes the code more maintainable and easier to test."
|
||||
|
||||
# Breaking change
|
||||
git commit -m "feat!: change API authentication method (#9)
|
||||
|
||||
BREAKING CHANGE: Authentication now requires app passwords instead of
|
||||
regular passwords. Update your config.json accordingly."
|
||||
```
|
||||
|
||||
### Issue References
|
||||
|
||||
- **Always include issue number**: `(#42)` in commit message
|
||||
- **Close issues** with keywords in PR description:
|
||||
- `Closes #42`
|
||||
- `Fixes #42`
|
||||
- `Resolves #42`
|
||||
|
||||
---
|
||||
|
||||
## Code Style
|
||||
|
||||
### C++
|
||||
- **Standard**: C++17
|
||||
- **Formatting**: Follow existing style (consider using clang-format)
|
||||
- **Naming**:
|
||||
- Classes: `PascalCase`
|
||||
- Functions/methods: `camelCase`
|
||||
- Variables: `snake_case`
|
||||
- Constants: `UPPER_SNAKE_CASE`
|
||||
- Namespaces: `lowercase`
|
||||
|
||||
### Python
|
||||
- **Standard**: PEP 8
|
||||
- **Formatting**: Use Black or autopep8
|
||||
|
||||
### Shell Scripts
|
||||
- **Use bash** explicitly: `#!/bin/bash`
|
||||
- **Quote variables**: `"${VAR}"`
|
||||
- **Check return codes**: `if [ $? -eq 0 ]; then`
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
- **Write tests** for all new features
|
||||
- **Run tests locally** before pushing:
|
||||
```bash
|
||||
# When available
|
||||
podman run --rm -v ./:/project:z builder ctest --test-dir build
|
||||
```
|
||||
- **Ensure CI passes** before requesting review
|
||||
|
||||
---
|
||||
|
||||
## Questions?
|
||||
|
||||
- **Open an issue** for questions
|
||||
- **Comment on relevant issues** for feature discussions
|
||||
- **Check existing documentation** in the `docs/` directory
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
By contributing to Nextcloud Share, you agree that your contributions will be licensed under the MIT License.
|
||||
|
||||
---
|
||||
|
||||
Thank you for contributing! 🎉
|
||||
Reference in New Issue
Block a user