Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The Contributing Guidelines for the Nextcloud CAD Viewer project establish the standards and procedures for participating in the development of this DWG/DXF viewing integration. This project relies on community contributions to maintain compatibility with Nextcloud and the upstream cad-viewer library. Contributors are expected to follow specific technical workflows for both backend (PHP) and frontend (Vue.js) development to ensure code quality and system stability.
Developers should familiarize themselves with the Architecture and Code Style before submitting changes. All participants must adhere to the community's shared values as outlined in the Code of Conduct.
Sources: README.md:204-214, CODE_OF_CONDUCT.md:1-12, wiki/Home.md:30-36
Community Standards
All contributors and users engaging with the Nextcloud team and community services are bound by the project's Code of Conduct. This ensures a productive, positive, and creative atmosphere for participants worldwide who create free software for a free internet.
Sources: CODE_OF_CONDUCT.md:1-12
Development Workflow
Contributing to the project follows a standard GitHub-based workflow. Contributors are required to fork the repository, develop features in isolated branches, and submit Pull Requests for review.
The diagram above illustrates the step-by-step process for submitting a contribution, from forking to the final Pull Request.
Sources: README.md:204-214
Environment Setup
The technical stack is split between a PHP backend and a Vue 3 frontend. Specific engine requirements must be met to ensure a consistent development environment.
| Component | Requirement | Purpose |
|---|---|---|
| PHP | ^8.2 | Backend logic and Nextcloud integration |
| Node.js | >= 24 | Frontend development and build tooling |
| pnpm | >= 10 | Package management (compatibility) |
| Nextcloud | 33 | Target platform for testing |
Sources: README.md:28-32, AGENTS.md:10-18
Backend Development (PHP)
The backend is built using the Nextcloud App Framework. Contributors must manage dependencies through Composer and ensure compatibility with the OCP (Original Core PHP) stable APIs for Nextcloud 33.
Dependency Management
When updating backend dependencies, use the following guidelines:
- Ensure compatibility with PHP 8.2.
- If the local environment differs from the target PHP version, use the
--ignore-platform-reqsflag during composer updates. - Nextcloud core classes are provided via
nextcloud/ocp:dev-stable33.
Backend Commands
| Task | Command |
|---|---|
| Install Dependencies | composer install |
| Run Unit Tests | composer test:unit |
| Static Analysis | composer psalm |
| Code Linting | npm run lint (via composer script) |
Sources: AGENTS.md:21-26, composer.json:34-45, AGENTS.md:32-35
Frontend Development (Vue.js)
The frontend utilizes Vue 3 and Element Plus. It integrates the @mlightcad/cad-viewer library to handle WebGL-based rendering of CAD files.
Critical NPM Instructions
Due to peer dependency conflicts within the @mlightcad packages, contributors must use the --legacy-peer-deps flag when installing frontend dependencies:
npm install --legacy-peer-deps
Sources: AGENTS.md:27-30
Build and Test Scripts
Frontend assets must be compiled using Webpack. The following scripts are defined in package.json:
npm run dev: Development build with watch mode for active coding sessions.npm run build: Production build (required before submitting any Pull Request).npm run lint: Executes ESLint on thesrc/directory.npm test: Runs the Jest test suite for frontend components and utilities.
Sources: package.json:12-19, README.md:120-136
Project Structure
Contributors should place code in the appropriate directories to maintain the architectural split:
src/: Vue.js frontend source code (components, router, utils).lib/: PHP backend logic (Controllers, Listeners, AppInfo).appinfo/: App metadata and route definitions.tests/: Unit and integration tests.
Sources: README.md:144-159
Testing Requirements
Before submitting a Pull Request, all changes must be verified through the project's testing suites.
The sequence diagram shows the validation steps a developer performs to ensure code quality before contribution.
Sources: AGENTS.md:32-40, package.json:17, composer.json:43
Reporting Issues
If a contribution is intended to fix a bug or add a feature, it should be linked to an issue in the tracker.
- Bug Reports: Use the provided template to include steps to reproduce, expected behavior, and environment details.
- Feature Requests: Describe the proposed change and its use case.
Sources: README.md:216-220, wiki/Home.md:65-66
Conclusion
Contributing to the Nextcloud CAD Viewer requires careful attention to the dual-stack architecture and the specific versioning requirements of the Nextcloud ecosystem. By following these guidelines, contributors help ensure that the application remains a reliable tool for viewing DWG and DXF files within Nextcloud.