nextcloud-share/CONTRIBUTING.md

# 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! 🎉