spacedrive/CONTRIBUTING.md

Welcome to the Spacedrive Contributing Guide

Thank you for investing your time in contributing to our project!

Please read our Code of Conduct to keep our community approachable and respectable.

This guide will provide an overview of the contribution workflow, including opening an issue, creating a pull request (PR), and the review and merge process.

New Contributor Guide

To familiarize yourself with the project, please read the README. Here are some resources to help you get started with open-source contributions:

• Finding ways to contribute to open-source on GitHub
• Setting up Git
• GitHub flow
• Collaborating with pull requests
• Getting started with Tauri
• pnpm CLI

Getting Started

Issues

Creating a New Issue

If you come across an issue or have a feature request for Spacedrive, please search if a related issue has already been reported. If no relevant issue exists, you can open a new issue using the appropriate issue form.

Solving an Issue

To find an issue that interests you, you can browse through our existing issues and use the available labels to narrow down your search (See Labels for more information). As a general rule, if you find an issue you want to work on, you are welcome to open a PR with a fix.

Making Changes

Making Changes Locally

This project uses Cargo and pnpm. Make sure you have them installed before proceeding.

To make changes locally, follow these steps:

1. Clone the repository: git clone https://github.com/spacedriveapp/spacedrive
2. Navigate to the project directory: cd spacedrive
3. Configure your system environment for Spacedrive development
   1. For Linux users, run: ./scripts/setup.sh

      This script will check if Rust and pnpm are installed then proceed to install Clang, NASM, LLVM, libvips, Gstreamer's Plugins, FFmpeg, Perl, Tauri essentials and any other required dependencies for Spacedrive to build.

   2. For macOS users, run: ./scripts/setup.sh

      This script will check if Rust, pnpm and Xcode are installed and proceed to use Homebrew to install NASM, Tauri essentials and install any other required dependencies for Spacedrive to build.

   3. For Windows users, run in PowerShell: .\scripts\setup.ps1

      This script will install pnpm, LLVM, FFmpeg, C++ build tools, NASM, Rust + Cargo, Rust tools, Edge Webview 2, Strawberry Perl, Tauri essentials and any other required dependencies for Spacedrive to build.

4. Install dependencies: pnpm i
5. Prepare the build: pnpm prep (This will run all necessary codegen and build required dependencies)

To quickly run only the desktop app after prep, you can use:

• pnpm tauri dev

  If necessary, the webview devtools can be opened by pressing Ctrl + Shift + I (Linux and Windows) or Command + Option + I (macOS) in the desktop app.

  Also, the react-devtools can be launched using pnpm dlx react-devtools. However, it must be executed before starting the desktop app for it to connect.

To run the web app:

• pnpm dev:web

This will start both the server and web interface. You can launch these individually if you'd prefer:

• cargo run -p sd-server (server)
• pnpm web dev (web interface)

To run the landing page:

• pnpm landing dev

If you encounter any issues, ensure that you are using the following versions of Rust, Node and Pnpm:

• Rust version: 1.73.0
• Node version: 18.17
• Pnpm version: 8.0.0

After cleaning out your build artifacts using pnpm clean, git clean, or cargo clean, it is necessary to re-run the setup-system script.

Make sure to read the guidelines to ensure that your code follows a similar style to ours.

Mobile App

To run the mobile app:

• Install Android Studio for Android and Xcode for iOS development.
• Run ./scripts/setup.sh mobile
  • This will set up most of the dependencies required to build the mobile app.
• Make sure you have NDK 23.1.7779620 and CMake installed in Android Studio.
• Run the following commands:
  • pnpm android (runs on Android Emulator)
  • pnpm ios (runs on iOS Emulator)
  • pnpm start (runs the metro bundler)

AppImage

Specific instructions on how to build an AppImage release are located here

Pull Request

Once you have finished making your changes, create a pull request (PR) to submit them.

• Fill out the "Ready for review" template to help reviewers understand your changes and the purpose of your PR.
• If you are addressing an existing issue, don't forget to link your PR to the issue.
• Enable the checkbox to allow maintainer edits so that the branch can be updated for merging.
• Once you submit your PR, a team member will review your proposal. They may ask questions or request additional information.
• You may be asked to make changes before the PR can be merged, either through suggested changes or pull request comments. You can apply suggested changes directly through the UI. For other changes, you can make them in your fork and commit them to your branch.
• As you update your PR and apply changes, mark each conversation as resolved.
• If you run into any merge issues, refer to this git tutorial to help you resolve merge conflicts and other issues.

Your PR is Merged!

Congratulations! 🎉🎉 The Spacedrive team thanks you for your contribution! ✨

Once your PR is merged, your changes will be included in the next release of the application.

Common Errors

xcrun: error: unable to find utility "xctest", not a developer tool or in PATH

This error occurs when Xcode is not installed or when the Xcode command line tools are not in your PATH.

To resolve this issue:

• Install Xcode from the macOS App Store or directly from here (requires Apple Account).
• Run xcode-select -s /Applications/Xcode.app/Contents/Developer. This command will use Xcode's developer tools instead of macOS's default tools.

unable to lookup item 'PlatformPath'

If you run into this issue, or similar:

error: terminated(1): /us/bin/xcrun --sdk macos --show-sdk-platform-path output :
xcrun: error: unable to lookup item 'PlatformPath' from command line tools installation xcrun: error: unable to lookup item 'PlatformPath' in SDK '/Library/Developer /CommandLineTools/SDKs/MacOSX.sdk'

Ensure that macOS is fully updated, and that you have Xcode installed (via the app store).

Once that has completed, run xcode-select --install in the terminal to install the command line tools. If they are already installed, ensure that you update macOS to the latest version available.

Also ensure that Rosetta is installed, as a few of our dependencies require it. You can install Rosetta with softwareupdate --install-rosetta --agree-to-license.

Credits

This CONTRIBUTING.md file was inspired by the github/docs CONTRIBUTING.md file, and we extend our gratitude to the original author.