From 7e2c013cdc40e2b571815b9368f0020aae7f581d Mon Sep 17 00:00:00 2001 From: Tom Hicks Date: Mon, 26 Jan 2026 23:19:48 -0800 Subject: [PATCH 1/3] Creates milestones, labels, and issues on gitea. --- .plans/CreateGiteaIssues.md | 1192 +++++++++++++++++++++++++++++++++++ 1 file changed, 1192 insertions(+) create mode 100644 .plans/CreateGiteaIssues.md diff --git a/.plans/CreateGiteaIssues.md b/.plans/CreateGiteaIssues.md new file mode 100644 index 0000000..5e9cd52 --- /dev/null +++ b/.plans/CreateGiteaIssues.md @@ -0,0 +1,1192 @@ +# Gitea Issues Creation Plan + +**Created**: 2026-01-26 +**Status**: Ready for Implementation +**Repository**: https://git.tomusan.com (nextcloud-share) + +--- + +## Overview + +This plan details all Gitea issues to be created for the Nextcloud Share project. Issues are organized into milestones/epics and include full descriptions, acceptance criteria, and labels. + +--- + +## Milestones + +### Milestone 1: Project Infrastructure +- **Goal**: Complete foundational setup (build system, config, CI/CD) +- **Issues**: #4, #5, #6, #7 +- **Target**: Sprint 1 + +### Milestone 2: Shared Library (libnextcloud) +- **Goal**: Core C++17 library with WebDAV support +- **Issues**: #8, #9, #10, #11, #12, #13 +- **Target**: Sprint 2-3 + +### Milestone 3: Nintendo 3DS App +- **Goal**: Functional 3DS homebrew application +- **Issues**: #14, #15, #16, #17, #18, #19 +- **Target**: Sprint 4-5 + +### Milestone 4: Documentation & Polish +- **Goal**: Complete user and developer documentation +- **Issues**: #20, #21 +- **Target**: Sprint 6 + +--- + +## Epic Issues + +### Issue #1: Project Infrastructure Setup +**Type**: Epic +**Labels**: `epic`, `infrastructure` +**Milestone**: Milestone 1 + +**Description**: +Set up foundational project infrastructure including repository configuration, build environments, configuration management, and CI/CD pipeline. + +**Scope**: +- Git-flow workflow configuration +- Docker/Podman build containers for all platforms +- Configuration file system with secrets management +- Gitea Actions CI/CD pipeline +- Build status badges + +**Related Issues**: #4, #5, #6, #7 + +**Acceptance Criteria**: +- [ ] Git-flow initialized with main/develop branches +- [ ] All platform build containers available and tested +- [ ] Config system working with env var overrides +- [ ] CI/CD pipeline running on every push/PR +- [ ] Build badges displayed in README + +--- + +### Issue #2: Shared Library Development (libnextcloud) +**Type**: Epic +**Labels**: `epic`, `library`, `core` +**Milestone**: Milestone 2 + +**Description**: +Develop the shared C++17 library that provides Nextcloud connectivity via WebDAV. This library will be used by all platform-specific applications. + +**Scope**: +- WebDAV protocol implementation +- HTTP/HTTPS client wrapper (libcurl + mbedTLS) +- Authentication (HTTP Basic Auth) +- File upload/download functionality +- Folder browsing and management +- Favorites and recent folders persistence +- Comprehensive test coverage with Google Test + +**Related Issues**: #8, #9, #10, #11, #12, #13 + +**Acceptance Criteria**: +- [ ] Public API defined and documented +- [ ] WebDAV client functional with test Nextcloud servers +- [ ] All core features implemented +- [ ] Test coverage >80% +- [ ] CMake build system complete +- [ ] API documentation generated + +--- + +### Issue #3: Nintendo 3DS Homebrew App +**Type**: Epic +**Labels**: `epic`, `platform:3ds` +**Milestone**: Milestone 3 + +**Description**: +Develop the Nintendo 3DS homebrew application that uses libnextcloud to upload screenshots and other files to Nextcloud. + +**Scope**: +- 3DS-specific UI implementation +- SD card file browser +- Integration with libnextcloud +- CIA and 3DSX packaging +- Settings persistence on 3DS + +**Related Issues**: #14, #15, #16, #17, #18, #19 + +**Acceptance Criteria**: +- [ ] Functional 3DS app with UI +- [ ] File browsing and selection working +- [ ] Successful uploads to Nextcloud +- [ ] Both CIA and 3DSX formats available +- [ ] Settings saved between sessions + +--- + +## Infrastructure Issues (Milestone 1) + +### Issue #4: Configure git-flow workflow +**Type**: Task +**Labels**: `infrastructure`, `setup` +**Milestone**: Milestone 1 +**Priority**: High +**Status**: ✅ COMPLETE + +**Description**: +Initialize and document the git-flow workflow for the project. This includes setting up the main and develop branches, and documenting the branching strategy for features, releases, and hotfixes. + +**Tasks**: +- [x] Create develop branch from main +- [x] Push both branches to remote +- [x] Document branching strategy in CONTRIBUTING.md +- [ ] Configure branch protection rules on Gitea (if available) + +**Acceptance Criteria**: +- [x] develop branch exists and is set as default +- [x] main branch represents production-ready code +- [ ] Documentation clearly explains workflow +- [ ] Team members understand branching strategy + +**Branch Strategy**: +- `main` - Production-ready releases only +- `develop` - Integration branch for features +- `feature/*` - New features (branch from develop, merge to develop) +- `release/*` - Release preparation (branch from develop, merge to main + develop) +- `hotfix/*` - Critical fixes (branch from main, merge to main + develop) + +--- + +### Issue #5: Create Docker build environment for devkitARM +**Type**: Task +**Labels**: `infrastructure`, `docker`, `platform:3ds` +**Milestone**: Milestone 1 +**Priority**: High + +**Description**: +Create a Docker/Podman container that includes devkitARM and all dependencies needed to build the Nintendo 3DS application. This ensures developers can build without installing platform toolchains locally. + +**Tasks**: +- [ ] Create `docker/devkitarm.Dockerfile` +- [ ] Base image: devkitpro/devkitarm or equivalent +- [ ] Install required tools: makerom, tex3ds, bannertool +- [ ] Add libctru, citro3d, citro2d libraries +- [ ] Add build dependencies: CMake, git, curl +- [ ] Create `scripts/build-3ds.sh` wrapper script +- [ ] Test container builds project successfully +- [ ] Document usage in `docker/README.md` +- [ ] Add podman commands to main README + +**Dockerfile Requirements**: +```dockerfile +FROM devkitpro/devkitarm:latest + +RUN apt-get update && apt-get install -y \ + cmake \ + git \ + curl \ + pkg-config + +# Verify devkitARM installation +RUN arm-none-eabi-gcc --version +``` + +**Acceptance Criteria**: +- [ ] Container builds without errors +- [ ] Can compile 3DS app inside container +- [ ] Volume mounts work correctly for source code +- [ ] Build artifacts accessible on host +- [ ] Documentation includes podman examples +- [ ] Container tagged and versioned + +**Podman Commands to Document**: +```bash +# Build container +podman build -f docker/devkitarm.Dockerfile -t nextcloud-share-3ds:latest . + +# Run build +podman run --rm -v ./:/project:z nextcloud-share-3ds make -C 3ds + +# Interactive shell +podman run --rm -it -v ./:/project:z nextcloud-share-3ds bash +``` + +--- + +### Issue #6: Set up configuration file system +**Type**: Task +**Labels**: `infrastructure`, `configuration` +**Milestone**: Milestone 1 +**Priority**: High + +**Description**: +Create the configuration file system for managing test credentials and build options. Implement environment variable overrides for CI/CD and create helper scripts to load configuration. + +**Tasks**: +- [ ] Create `config.example.json` with template +- [ ] Add `config.json` to .gitignore +- [ ] Create `scripts/load-config.sh` to parse JSON and export env vars +- [ ] Document environment variable overrides in README +- [ ] Add validation for required config fields +- [ ] Create `scripts/validate-config.sh` +- [ ] Update README with configuration instructions + +**config.example.json Structure**: +```json +{ + "nextcloud": { + "url": "https://cloud.example.com", + "username": "your-username", + "password": "your-password" + }, + "settings": { + "maxRecentFolders": 5, + "uploadChunkSize": 10485760 + } +} +``` + +**scripts/load-config.sh Logic**: +```bash +#!/bin/bash +# Load config from JSON, allowing env var overrides + +CONFIG_FILE="${CONFIG_FILE:-config.json}" + +if [ ! -f "$CONFIG_FILE" ]; then + echo "Warning: $CONFIG_FILE not found, using environment variables only" +fi + +# Load from config.json if not set in environment +export NEXTCLOUD_URL="${NEXTCLOUD_URL:-$(jq -r '.nextcloud.url' "$CONFIG_FILE" 2>/dev/null)}" +export NEXTCLOUD_USER="${NEXTCLOUD_USER:-$(jq -r '.nextcloud.username' "$CONFIG_FILE" 2>/dev/null)}" +export NEXTCLOUD_PASSWORD="${NEXTCLOUD_PASSWORD:-$(jq -r '.nextcloud.password' "$CONFIG_FILE" 2>/dev/null)}" + +# Validate required vars +if [ -z "$NEXTCLOUD_URL" ]; then + echo "Error: NEXTCLOUD_URL not set" + exit 1 +fi +``` + +**Environment Variables**: +- `NEXTCLOUD_URL` - Override Nextcloud server URL +- `NEXTCLOUD_USER` - Override username +- `NEXTCLOUD_PASSWORD` - Override password +- `CONFIG_FILE` - Path to config file (default: config.json) + +**Acceptance Criteria**: +- [ ] config.example.json created and documented +- [ ] load-config.sh correctly parses JSON +- [ ] Environment variables take precedence over JSON +- [ ] Validation script catches missing required fields +- [ ] Documentation clear for new developers +- [ ] CI can inject credentials via env vars + +--- + +### Issue #7: Implement Gitea CI/CD pipeline +**Type**: Task +**Labels**: `infrastructure`, `ci-cd`, `gitea` +**Milestone**: Milestone 1 +**Priority**: Medium + +**Description**: +Set up Gitea Actions (or webhooks) to automatically build, test, and report status on every push and pull request. Include build status badges in README. + +**Tasks**: +- [ ] Create `.gitea/workflows/build.yml` +- [ ] Configure workflow triggers (push, pull_request) +- [ ] Build shared library in container +- [ ] Run Google Test suite +- [ ] Build 3DS app (when available) +- [ ] Generate build artifacts +- [ ] Add build status badge to README +- [ ] Configure secret variables for test credentials +- [ ] Test with actual PR + +**Workflow Structure**: +```yaml +name: Build and Test + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ develop ] + +jobs: + test-library: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Build shared library + run: | + 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 + - name: Run tests + run: | + podman run --rm -v ./:/project:z builder ctest --test-dir build + env: + NEXTCLOUD_URL: ${{ secrets.NEXTCLOUD_TEST_URL }} + NEXTCLOUD_USER: ${{ secrets.NEXTCLOUD_TEST_USER }} + NEXTCLOUD_PASSWORD: ${{ secrets.NEXTCLOUD_TEST_PASSWORD }} + + build-3ds: + runs-on: ubuntu-latest + needs: test-library + steps: + - uses: actions/checkout@v3 + - name: Build 3DS app + run: | + podman build -f docker/devkitarm.Dockerfile -t 3ds-builder . + podman run --rm -v ./:/project:z 3ds-builder make -C 3ds + - name: Upload artifacts + uses: actions/upload-artifact@v3 + with: + name: 3ds-builds + path: | + 3ds/build/*.cia + 3ds/build/*.3dsx +``` + +**Gitea Secrets to Configure**: +- `NEXTCLOUD_TEST_URL` +- `NEXTCLOUD_TEST_USER` +- `NEXTCLOUD_TEST_PASSWORD` + +**Acceptance Criteria**: +- [ ] Workflow runs on every push to main/develop +- [ ] Workflow runs on every PR to develop +- [ ] Build failures are reported in PR +- [ ] Test results visible in workflow log +- [ ] Build artifacts downloadable +- [ ] Status badge shows current build status +- [ ] Secrets properly configured and working + +--- + +## Shared Library Issues (Milestone 2) + +### Issue #8: Design and implement WebDAV client +**Type**: Feature +**Labels**: `library`, `core`, `networking` +**Milestone**: Milestone 2 +**Priority**: High + +**Description**: +Implement a C++17 WebDAV client for communicating with Nextcloud servers. This is the core networking component that handles HTTP/HTTPS requests using libcurl with mbedTLS. + +**Tasks**: +- [ ] Create `shared/include/nextcloud/webdav_client.hpp` +- [ ] Implement HTTP wrapper around libcurl +- [ ] Add SSL/TLS support with mbedTLS +- [ ] Implement WebDAV methods: + - [ ] PROPFIND (list folders/files) + - [ ] PUT (upload files) + - [ ] MKCOL (create folders) + - [ ] DELETE (delete files/folders) + - [ ] MOVE (rename/move files) +- [ ] Parse WebDAV XML responses using tinyxml2 +- [ ] Implement proper error handling +- [ ] Add timeout and retry logic +- [ ] Write unit tests with mocked HTTP responses +- [ ] Document API in Doxygen format + +**API Design**: +```cpp +namespace nextcloud { + +class WebDAVClient { +public: + WebDAVClient(const std::string& base_url); + + // Authentication + void setBasicAuth(const std::string& username, const std::string& password); + + // Operations + bool uploadFile(const std::string& local_path, const std::string& remote_path, + ProgressCallback callback = nullptr); + std::vector listFolder(const std::string& remote_path); + bool createFolder(const std::string& remote_path); + bool deleteItem(const std::string& remote_path); + bool moveItem(const std::string& from, const std::string& to); + + // Connection testing + bool testConnection(); + +private: + std::string base_url_; + std::unique_ptr http_client_; +}; + +} // namespace nextcloud +``` + +**Dependencies**: +- libcurl 7.68+ +- mbedTLS 2.16+ +- tinyxml2 9.0+ + +**Acceptance Criteria**: +- [ ] All WebDAV methods implemented +- [ ] SSL/TLS connections working +- [ ] XML responses correctly parsed +- [ ] Error handling comprehensive +- [ ] Unit tests with >80% coverage +- [ ] API documented +- [ ] Works with test Nextcloud servers + +--- + +### Issue #9: Implement authentication system +**Type**: Feature +**Labels**: `library`, `core`, `security` +**Milestone**: Milestone 2 +**Priority**: High + +**Description**: +Implement HTTP Basic Authentication for Nextcloud. Include credential validation, secure storage, and session management. + +**Tasks**: +- [ ] Create `shared/include/nextcloud/auth.hpp` +- [ ] Implement HTTP Basic Auth encoding +- [ ] Add credential validation +- [ ] Implement connection verification +- [ ] Handle authentication errors properly +- [ ] Add support for app passwords +- [ ] Write unit tests for auth flow +- [ ] Document security considerations + +**API Design**: +```cpp +namespace nextcloud { + +class AuthManager { +public: + struct Credentials { + std::string username; + std::string password; + }; + + // Validate credentials against server + static bool validateCredentials(const std::string& server_url, + const Credentials& creds); + + // Encode credentials for Basic Auth header + static std::string encodeBasicAuth(const Credentials& creds); + + // Test if credentials work + static bool testAuthentication(WebDAVClient& client); +}; + +} // namespace nextcloud +``` + +**Security Considerations**: +- Always use HTTPS (reject plain HTTP) +- Support Nextcloud app-specific passwords +- Clear passwords from memory when done +- Validate server certificates + +**Acceptance Criteria**: +- [ ] Basic Auth implementation complete +- [ ] Credentials validated before use +- [ ] Proper error messages for auth failures +- [ ] Works with app passwords +- [ ] Security best practices followed +- [ ] Unit tests passing + +--- + +### Issue #10: Implement file upload functionality +**Type**: Feature +**Labels**: `library`, `core`, `feature` +**Milestone**: Milestone 2 +**Priority**: High + +**Description**: +Implement file upload functionality with streaming, progress tracking, and chunked uploads for large files. Support pause/resume if possible. + +**Tasks**: +- [ ] Create `shared/include/nextcloud/upload_manager.hpp` +- [ ] Implement streaming file uploads +- [ ] Add chunked upload support for large files +- [ ] Implement progress callback system +- [ ] Handle upload errors and retries +- [ ] Add bandwidth throttling (optional) +- [ ] Calculate and verify checksums (optional) +- [ ] Write unit tests +- [ ] Write integration tests with actual uploads + +**API Design**: +```cpp +namespace nextcloud { + +using ProgressCallback = std::function; + +class UploadManager { +public: + struct UploadOptions { + size_t chunk_size = 10 * 1024 * 1024; // 10MB default + int max_retries = 3; + ProgressCallback progress_callback; + }; + + explicit UploadManager(WebDAVClient& client); + + bool uploadFile(const std::string& local_path, + const std::string& remote_path, + const UploadOptions& options = {}); + + bool uploadData(const std::vector& data, + const std::string& remote_path); + + void cancelUpload(); + +private: + WebDAVClient& client_; + std::atomic cancel_flag_; +}; + +} // namespace nextcloud +``` + +**Acceptance Criteria**: +- [ ] Single file uploads working +- [ ] Chunked uploads for large files +- [ ] Progress callbacks functional +- [ ] Retry logic handles transient errors +- [ ] Can upload to test Nextcloud +- [ ] Unit and integration tests passing + +--- + +### Issue #11: Implement folder management +**Type**: Feature +**Labels**: `library`, `core`, `feature` +**Milestone**: Milestone 2 +**Priority**: Medium + +**Description**: +Implement folder browsing, creation, and navigation on Nextcloud. Parse PROPFIND responses to get folder contents. + +**Tasks**: +- [ ] Create `shared/include/nextcloud/folder_manager.hpp` +- [ ] Implement folder listing (PROPFIND) +- [ ] Parse XML responses to extract file/folder info +- [ ] Implement folder creation (MKCOL) +- [ ] Add folder deletion +- [ ] Handle nested folder creation +- [ ] Cache folder contents (optional) +- [ ] Write unit tests with mock XML responses + +**API Design**: +```cpp +namespace nextcloud { + +struct FileInfo { + std::string name; + std::string path; + bool is_directory; + uint64_t size; + std::time_t modified_time; +}; + +class FolderManager { +public: + explicit FolderManager(WebDAVClient& client); + + std::vector listFolder(const std::string& remote_path); + bool createFolder(const std::string& remote_path); + bool createFolderRecursive(const std::string& remote_path); + bool deleteFolder(const std::string& remote_path); + bool folderExists(const std::string& remote_path); + +private: + WebDAVClient& client_; +}; + +} // namespace nextcloud +``` + +**Acceptance Criteria**: +- [ ] Can list folder contents +- [ ] Correctly parses file/folder metadata +- [ ] Can create single folders +- [ ] Can create nested folder structures +- [ ] Error handling for invalid paths +- [ ] Unit tests passing +- [ ] Works with test Nextcloud + +--- + +### Issue #12: Implement favorites and recent folders +**Type**: Feature +**Labels**: `library`, `feature` +**Milestone**: Milestone 2 +**Priority**: Low + +**Description**: +Implement a persistence layer to store user's favorite folders and track recently used folders. This data should be saved to a JSON file on the device. + +**Tasks**: +- [ ] Create `shared/include/nextcloud/folder_history.hpp` +- [ ] Implement favorites storage +- [ ] Implement recent folders tracking (LRU cache) +- [ ] Make max recent folders configurable +- [ ] Save/load from JSON file +- [ ] Handle file I/O errors gracefully +- [ ] Write unit tests + +**API Design**: +```cpp +namespace nextcloud { + +class FolderHistory { +public: + explicit FolderHistory(size_t max_recent = 5); + + // Load from file + bool load(const std::string& file_path); + bool save(const std::string& file_path); + + // Favorites + void addFavorite(const std::string& path); + void removeFavorite(const std::string& path); + std::vector getFavorites() const; + bool isFavorite(const std::string& path) const; + + // Recent folders (LRU) + void addRecent(const std::string& path); + std::vector getRecent() const; + +private: + size_t max_recent_; + std::vector favorites_; + std::deque recent_; +}; + +} // namespace nextcloud +``` + +**JSON Format**: +```json +{ + "favorites": [ + "/Photos", + "/Screenshots", + "/Videos" + ], + "recent": [ + "/Photos/2026", + "/Screenshots", + "/Documents" + ] +} +``` + +**Acceptance Criteria**: +- [ ] Can add/remove favorites +- [ ] Recent folders LRU working +- [ ] Persists to JSON file +- [ ] Loads correctly on startup +- [ ] Max recent folders respected +- [ ] Unit tests passing + +--- + +### Issue #13: Write unit tests for shared library +**Type**: Task +**Labels**: `library`, `testing` +**Milestone**: Milestone 2 +**Priority**: High + +**Description**: +Comprehensive unit test suite using Google Test for all shared library components. Include mock HTTP responses for testing without network. + +**Tasks**: +- [ ] Set up Google Test framework in CMake +- [ ] Create test directory structure +- [ ] Write tests for WebDAVClient +- [ ] Write tests for AuthManager +- [ ] Write tests for UploadManager +- [ ] Write tests for FolderManager +- [ ] Write tests for FolderHistory +- [ ] Create mock HTTP server for integration tests +- [ ] Set up test fixtures +- [ ] Configure test data files +- [ ] Add tests to CI pipeline +- [ ] Generate coverage report + +**Test Structure**: +``` +shared/tests/ +├── CMakeLists.txt +├── test_webdav_client.cpp +├── test_auth.cpp +├── test_upload.cpp +├── test_folder_manager.cpp +├── test_folder_history.cpp +├── mocks/ +│ ├── mock_http_client.hpp +│ └── mock_server.cpp +└── fixtures/ + └── test_responses.xml +``` + +**Coverage Goals**: +- WebDAVClient: >80% +- AuthManager: >90% +- UploadManager: >75% +- FolderManager: >80% +- FolderHistory: >85% + +**Acceptance Criteria**: +- [ ] All components have unit tests +- [ ] Tests run in CI pipeline +- [ ] Mock HTTP server working +- [ ] Coverage meets goals +- [ ] Tests well-documented +- [ ] Fast test execution (<30 seconds) + +--- + +## 3DS Platform Issues (Milestone 3) + +### Issue #14: Initialize 3DS project structure +**Type**: Task +**Labels**: `platform:3ds`, `setup` +**Milestone**: Milestone 3 +**Priority**: High + +**Description**: +Set up the 3DS project structure with devkitARM build files, basic app skeleton, and integration with the shared library. + +**Tasks**: +- [ ] Create `3ds/` directory structure +- [ ] Create Makefile for devkitARM +- [ ] Set up icon and banner resources +- [ ] Create basic app initialization code +- [ ] Link shared library in build +- [ ] Create app metadata (title, author, version) +- [ ] Test build in Docker container +- [ ] Document 3DS-specific build steps + +**Directory Structure**: +``` +3ds/ +├── src/ +│ ├── main.cpp +│ ├── app.cpp +│ └── app.hpp +├── resources/ +│ ├── icon.png +│ ├── banner.png +│ └── audio.wav (banner audio) +├── build/ +├── Makefile +└── README.md +``` + +**Makefile Requirements**: +- Link with libnextcloud +- Include libctru, citro2d +- Support CIA and 3DSX output +- Include network libraries + +**Acceptance Criteria**: +- [ ] Project structure created +- [ ] Makefile builds successfully +- [ ] App runs on 3DS/Citra emulator +- [ ] Shared library linked correctly +- [ ] Icon and banner display +- [ ] Documentation complete + +--- + +### Issue #15: Implement 3DS UI framework +**Type**: Feature +**Labels**: `platform:3ds`, `ui` +**Milestone**: Milestone 3 +**Priority**: High + +**Description**: +Implement the UI framework for the 3DS app using citro2d. Create a menu system with screens for server config, file browsing, and settings. + +**Tasks**: +- [ ] Set up citro2d/citro3d rendering +- [ ] Create screen manager for navigation +- [ ] Implement main menu screen +- [ ] Create on-screen keyboard for text input +- [ ] Implement message dialogs +- [ ] Add progress bar widget +- [ ] Create loading indicator +- [ ] Handle button input +- [ ] Add touch screen support +- [ ] Implement UI themes/colors + +**Screen Hierarchy**: +``` +Main Menu +├── Upload Files (→ File Browser) +├── Server Settings (→ Settings Screen) +├── Favorites (→ Folder List) +└── Exit +``` + +**UI Components Needed**: +- Menu lists +- Text input dialogs +- Confirmation dialogs +- Progress bars +- Loading spinners +- Keyboard overlay + +**Acceptance Criteria**: +- [ ] UI renders on both screens +- [ ] Touch and button input working +- [ ] Screen navigation functional +- [ ] Text input working +- [ ] Progress indicators visible +- [ ] Responsive and smooth + +--- + +### Issue #16: Implement SD card file browser +**Type**: Feature +**Labels**: `platform:3ds`, `feature` +**Milestone**: Milestone 3 +**Priority**: High + +**Description**: +Implement a file browser for the 3DS SD card to allow users to select screenshots, videos, and other files for upload. + +**Tasks**: +- [ ] Implement SD card access using libctru +- [ ] Create file browser UI +- [ ] Add folder navigation +- [ ] Show file details (size, date) +- [ ] Add file filtering (images, videos, all) +- [ ] Implement multi-file selection +- [ ] Add thumbnail preview for images (optional) +- [ ] Handle large directories efficiently +- [ ] Add sort options (name, date, size) + +**Screenshot Locations**: +- `/Nintendo 3DS/[ID]/[ID]/title/[TID]/screenshots/` +- SD card root + +**Acceptance Criteria**: +- [ ] Can browse SD card folders +- [ ] Can select files for upload +- [ ] File details displayed +- [ ] Filtering works +- [ ] Multi-select supported +- [ ] Performance acceptable + +--- + +### Issue #17: Integrate shared library with 3DS app +**Type**: Task +**Labels**: `platform:3ds`, `integration` +**Milestone**: Milestone 3 +**Priority**: High + +**Description**: +Integrate libnextcloud with the 3DS app. Set up network stack, handle connections, and implement upload functionality. + +**Tasks**: +- [ ] Initialize 3DS network stack (SOC) +- [ ] Link libnextcloud in Makefile +- [ ] Configure libcurl for 3DS +- [ ] Configure mbedTLS for 3DS +- [ ] Implement upload workflow +- [ ] Handle network errors gracefully +- [ ] Add connection status indicator +- [ ] Test uploads to Nextcloud +- [ ] Handle app suspend/resume + +**Network Stack Initialization**: +```cpp +// Initialize SOC (Socket) +Result soc_init = socInit(SOC_BUFFER, SOC_BUFFER_SIZE); +if (R_FAILED(soc_init)) { + // Handle error +} + +// At exit +socExit(); +``` + +**Acceptance Criteria**: +- [ ] Network stack initializes +- [ ] libnextcloud functions called successfully +- [ ] Can upload files to Nextcloud +- [ ] Error messages displayed to user +- [ ] Network errors handled gracefully +- [ ] App doesn't crash on suspend/resume + +--- + +### Issue #18: Implement 3DS settings screen +**Type**: Feature +**Labels**: `platform:3ds`, `ui`, `feature` +**Milestone**: Milestone 3 +**Priority**: Medium + +**Description**: +Create a settings screen where users can configure their Nextcloud server URL, username, and password. Settings should persist across app restarts. + +**Tasks**: +- [ ] Create settings screen UI +- [ ] Implement server URL input +- [ ] Implement username/password input +- [ ] Add connection test button +- [ ] Save settings to SD card +- [ ] Load settings on startup +- [ ] Validate URL format +- [ ] Show connection status +- [ ] Add clear credentials option + +**Settings Storage**: +- Location: `/3ds/nextcloud-share/config.json` +- Format: JSON (using nlohmann/json) +- Encrypted password storage (optional) + +**Settings UI**: +``` +Server Settings +├── Server URL: [https://cloud.example.com] +├── Username: [username] +├── Password: [••••••••] +├── Test Connection [Button] +└── Save [Button] +``` + +**Acceptance Criteria**: +- [ ] Settings screen functional +- [ ] Can input all credentials +- [ ] Connection test works +- [ ] Settings persist correctly +- [ ] URL validation working +- [ ] Clear error messages + +--- + +### Issue #19: Create CIA and 3DSX distribution packages +**Type**: Task +**Labels**: `platform:3ds`, `distribution` +**Milestone**: Milestone 3 +**Priority**: Medium + +**Description**: +Set up packaging for both CIA (installable) and 3DSX (Homebrew Launcher) formats. Include proper metadata, icons, and banners. + +**Tasks**: +- [ ] Configure makerom for CIA generation +- [ ] Create proper icon (48x48 and 24x24) +- [ ] Create banner image (256x128) +- [ ] Add banner audio +- [ ] Set up app metadata in Makefile +- [ ] Configure app permissions +- [ ] Test CIA installation +- [ ] Test 3DSX in Homebrew Launcher +- [ ] Automate packaging in CI +- [ ] Create release script + +**App Metadata**: +- Title: "Nextcloud Share" +- Author: "Tom Hicks" +- Description: "Upload files to Nextcloud" +- Version: Managed in Makefile + +**Required Tools**: +- makerom (CIA generation) +- 3dsxtool (3DSX generation) +- bannertool (banner creation) +- tex3ds (texture conversion) + +**Acceptance Criteria**: +- [ ] CIA builds successfully +- [ ] 3DSX builds successfully +- [ ] CIA installs on 3DS +- [ ] 3DSX runs from Homebrew Launcher +- [ ] Icon and banner display correctly +- [ ] Automated build process working +- [ ] Both formats in CI artifacts + +--- + +## Documentation Issues (Milestone 4) + +### Issue #20: Write user documentation +**Type**: Documentation +**Labels**: `documentation`, `user-facing` +**Milestone**: Milestone 4 +**Priority**: Medium + +**Description**: +Create comprehensive user documentation including installation guides, configuration instructions, and usage tutorials for each platform. + +**Tasks**: +- [ ] Create `docs/` directory structure +- [ ] Write installation guide for 3DS +- [ ] Write configuration guide +- [ ] Create step-by-step usage guide +- [ ] Add screenshots/photos +- [ ] Write FAQ section +- [ ] Write troubleshooting guide +- [ ] Add video tutorial (optional) +- [ ] Translate to other languages (optional) + +**Documentation Structure**: +``` +docs/ +├── user-guide/ +│ ├── installation-3ds.md +│ ├── configuration.md +│ ├── usage.md +│ └── screenshots/ +├── faq.md +└── troubleshooting.md +``` + +**Topics to Cover**: +- How to install CIA files +- How to use Homebrew Launcher +- How to configure Nextcloud server +- How to browse and select files +- How to upload files +- How to manage favorites +- Common errors and solutions + +**Acceptance Criteria**: +- [ ] Installation instructions clear +- [ ] Configuration steps documented +- [ ] Usage guide with examples +- [ ] FAQ answers common questions +- [ ] Troubleshooting covers common issues +- [ ] Screenshots included +- [ ] Tested by new users + +--- + +### Issue #21: Write developer documentation +**Type**: Documentation +**Labels**: `documentation`, `developer` +**Milestone**: Milestone 4 +**Priority**: Medium + +**Description**: +Create developer documentation including architecture overview, API documentation, build instructions, and contributing guidelines. + +**Tasks**: +- [ ] Write architecture overview +- [ ] Generate API docs with Doxygen +- [ ] Document build process +- [ ] Create contributing guidelines +- [ ] Write code style guide +- [ ] Document testing procedures +- [ ] Add platform porting guide +- [ ] Create release process docs +- [ ] Document CI/CD setup + +**Documentation Structure**: +``` +docs/ +├── developer/ +│ ├── architecture.md +│ ├── api/ +│ │ └── (Doxygen generated) +│ ├── building.md +│ ├── testing.md +│ ├── porting.md +│ └── releasing.md +├── CONTRIBUTING.md +└── CODE_STYLE.md +``` + +**Topics to Cover**: +- System architecture diagram +- Library API reference +- How to build for each platform +- How to run tests +- How to add new platforms +- Code style requirements +- PR process +- Release checklist + +**Acceptance Criteria**: +- [ ] Architecture clearly explained +- [ ] API fully documented +- [ ] Build instructions tested +- [ ] Contributing guide complete +- [ ] Code style defined +- [ ] Testing docs clear +- [ ] Porting guide useful +- [ ] Release process documented + +--- + +## Issue Creation Order + +**Recommended creation order**: +1. Epic issues (#1, #2, #3) - for overall tracking +2. Infrastructure issues (#4-#7) - immediate tasks +3. Library issues (#8-#13) - core development +4. Platform issues (#14-#19) - after library is stable +5. Documentation issues (#20-#21) - ongoing, final polish + +--- + +## Labels to Create in Gitea + +**Type Labels**: +- `epic` - Epic/milestone tracking issues +- `feature` - New features +- `task` - Implementation tasks +- `bug` - Bug fixes +- `documentation` - Documentation updates + +**Component Labels**: +- `infrastructure` - Build, CI/CD, setup +- `library` - Shared library code +- `core` - Core functionality +- `ui` - User interface +- `networking` - Network/HTTP code +- `security` - Security-related + +**Platform Labels**: +- `platform:3ds` - Nintendo 3DS specific +- `platform:wiiu` - Wii U specific +- `platform:switch` - Switch specific +- `platform:vita` - PS Vita specific + +**Priority Labels**: +- `priority:high` - Must have for release +- `priority:medium` - Should have +- `priority:low` - Nice to have + +**Status Labels**: +- `status:blocked` - Blocked by other issues +- `status:in-progress` - Currently being worked on +- `status:review` - In code review + +--- + +## Next Steps + +1. Create labels in Gitea +2. Create milestone definitions +3. Create epic issues (#1-#3) first +4. Create remaining issues in order +5. Link related issues together +6. Assign initial priorities +7. Begin working on infrastructure issues + +--- + +## Notes + +- All issues should reference related issues +- Include acceptance criteria in each issue +- Update issues as requirements change +- Close issues only when fully tested +- Use issue numbers in commit messages: `git commit -m "feat: implement WebDAV client (#8)"` -- 2.49.1 From 631046df34ed293fdbac5d32e7a242af702a2df7 Mon Sep 17 00:00:00 2001 From: Tom Hicks Date: Mon, 26 Jan 2026 23:42:08 -0800 Subject: [PATCH 2/3] Adds reference api info for gitea to gitignore. --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 9ac71d4..88f1b85 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,9 @@ config !config.example !*.config.example +# Gitea API documentation (downloaded for reference, not part of source) +gitea-swagger.v1.json + # Build artifacts build/ *.o -- 2.49.1 From 092299ff33b6aa2265fa4db2c1b1ac672b50aef8 Mon Sep 17 00:00:00 2001 From: Tom Hicks Date: Tue, 27 Jan 2026 00:10:27 -0800 Subject: [PATCH 3/3] feat(config): implement configuration system and contributing guide (#6, #4) --- .gitignore | 3 +- CONTRIBUTING.md | 410 +++++++++++++++++++++++++++++++++++++ config.example.json | 11 + docs/configuration.md | 203 ++++++++++++++++++ scripts/load-config.sh | 69 +++++++ scripts/validate-config.sh | 73 +++++++ 6 files changed, 767 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 config.example.json create mode 100644 docs/configuration.md create mode 100755 scripts/load-config.sh create mode 100755 scripts/validate-config.sh diff --git a/.gitignore b/.gitignore index 88f1b85..0c01580 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,6 @@ # Local configuration files (contain secrets - do NOT commit) # Developers should copy config.example to config and add their test credentials -config -*.config +config.json !config.example !*.config.example diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6c8f2a7 --- /dev/null +++ b/CONTRIBUTING.md @@ -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/-` + - 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` + - 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-` + - 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 +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 `#` in commit messages +- **Close issues** with "Closes #" or "Fixes #" in PR description + +--- + +## Commit Message Guidelines + +We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. + +### Format + +``` +(): (#) + + + +