Skip to content

Latest commit

 

History

History
252 lines (170 loc) · 12.6 KB

CONTRIBUTING.md

File metadata and controls

252 lines (170 loc) · 12.6 KB
Raw

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:

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

Web-based Clients

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

To make changes locally, follow these steps:

  1. Clone & enter the repository: git clone https://github.com/spacedriveapp/spacedrive && cd spacedrive Alternatively, if you’ve already cloned the repo locally, pull the latest changes with: git pull

Tip

Consider running pnpm clean after pulling the repository if you're returning to it from previously to avoid old files conflicting.

  1. Configure your system environment for Spacedrive development
  • For Unix users (Linux / macOS), run: ./scripts/setup.sh
  • For Windows users, run: .\scripts\setup.ps1 via PowerShell.

Note

This script (Unix / Windows) will check for if Rust and pnpm are installed then proceed to install any other required dependencies for Spacedrive to build via your system's respective package manager.

  1. Install NodeJS dependencies: pnpm i
  2. Prepare the build: pnpm prep. This will run all necessary codegen and build required dependencies.

Tip

Linux & macOS users can download a bundle of sample files for testing via pnpm test-data (requires curl & tar)

The test files will be located in a directory called test-data in the root of the Spacedrive repository.

To run the desktop app, run:

pnpm tauri dev

Note

The Tauri desktop app always runs its own instance of the backend and will not connect to a separately initiated sd-server instance.

To run the backend server, run:

cargo run -p sd-server

Tip

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

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

To run the web app (requires the backend to be running), run:

pnpm web dev

Tip

You can also quickly launch the web interface together with the backend with:

pnpm dev:web

To run the e2e tests for the web app:

pnpm web test:e2e

If you are developing a new test, you can execute Cypress in interactive mode with:

pnpm web test:interactive

Troubleshooting

  • If you encounter any issues, ensure that you are using the following versions of Rust, Node.js and pnpm:
    tool version
    Rust 1.81
    Node.js 18.18
    pnpm 9.4.0

Note: If you get a local migration error in development, you might need to set the following environment variables: database documentation.

rustup & nvm should both pick up on the appropriate versions of the Rust Toolchain & Node respectively from the project automatically.

  • After cleaning out your build artifacts using pnpm clean, it's necessary to re-run pnpm prep.

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

  • After you finish making your changes and committing them to your branch, make sure to execute pnpm autoformat to fix any style inconsistency in your code.

Landing Page

To run the landing page, run:

  • pnpm landing dev

Mobile App

To run the mobile app:

  • Run ./scripts/setup.sh mobile

Android

  • Install Java JDK 17 for Android. Java 21 is not compatible.
  • Install Android Studio. This will set up most of the dependencies required to build the mobile app.
  • Run pnpm mobile android to build the core and begin debugging the app.

Tip

To speed up compilation for Android you may temporarily remove unnecessary architectures from the build by removing them from the following line:

spacedrive/apps/mobile/modules/sd-core/android/build.sh

Line 61 in d180261

ANDROID_BUILD_TARGET_LIST="arm64-v8a armeabi-v7a x86_64"
Most modern phones use arm64-v8a while the Android Studio embedded emulator runs x86_64

If you wish to debug directly on a local Android device:

Tip

To access the logs from sd-core when running on device, run the following command:

adb logcat | grep -i com.spacedrive.app

iOS

  • Install the latest version of Xcode and Simulator if you wish to emulate an iOS device on your Mac.
    • When running Xcode for the first time, make sure to select the latest version of iOS.
  • Run pnpm mobile ios in the terminal to build & run the app on the Simulator.
    • To run the app in debug mode with backend (sd-core) logging, comment out the following lines before running the above command:

      spacedrive/apps/mobile/modules/sd-core/ios/build-rust.sh

      Lines 51 to 54 in d180261

      if [ "${CONFIGURATION:-}" = "Release" ]; then
      set -- --release
      TARGET_CONFIG=release
      fi
      You can now get backend (sd-core) logs from the Simulator by running the following command: 
      xcrun simctl launch --console booted com.spacedrive.app
  • If you'd like to run the app on device, run: pnpm mobile ios --device

Important

Note that you can only get sd-core logs from the app when running it on device by running the frontend and backend separately.

To run the backend (sd-core) separately, open up Xcode by running:

xed apps/mobile/ios

Select from the top if you wish to start on device or Simulator, and press play.

Select Device Run the App Build & Core logs are found here

To run the frontend, run the following:

pnpm mobile start

Important

The frontend is not functional without the sd-core running as well.

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.

Translations

Check out the i18n README for more information on how to contribute to translations.

Credits

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