maj/nextcloud-share
1
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e2d31dc0534053aa3d6eab3574ba7bda64cec56a
nextcloud-share/CONTRIBUTING.md

9.6 KiB
Raw Blame History

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

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: 
    git clone https://git.tomusan.com/maj/nextcloud-share.git
cd nextcloud-share
  3. Add upstream remote (if forked): 
    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:

git checkout develop
git pull origin develop
git checkout -b feature/8-webdav-client

Merging a feature:

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:

git checkout develop
git checkout -b release/v0.1.0
# Bump version numbers, update CHANGELOG, etc.

Finishing a release:

# 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:

git checkout main
git checkout -b hotfix/v0.1.1-fix-crash
# Make the fix

Finishing a hotfix:

# 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:

    cp config.example.json config.json

  2. Edit config.json with your Nextcloud test credentials:

    {
  "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:

# 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
  • Create a new issue if needed
  • Get issue number (e.g., #42)

2. Create a Feature Branch

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:

git add <files>
git commit -m "feat: add WebDAV client implementation (#42)"

5. Keep Your Branch Updated

git checkout develop
git pull origin develop
git checkout feature/42-short-description
git rebase develop

6. Push Your Branch

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 #" or "Fixes #" in PR description

Commit Message Guidelines

We follow the Conventional Commits 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

# 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: 
    # 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 View Git Blame Copy Permalink