Skip to content

Latest commit

 

History

History
419 lines (277 loc) · 17.4 KB

CONTRIBUTING.md

File metadata and controls

419 lines (277 loc) · 17.4 KB

Contributor Guidelines

Advice for new contributors

Start small. The PRs most likely to be merged are the ones that make small, easily reviewed changes with clear and specific intentions.

Guidelines on Pull Requests.

It's a good idea to gauge interest in your intended work by finding the current issue for it or creating a new one yourself. Use Github issues as a place to signal your intentions and get feedback from the users most likely to appreciate your changes.

You're most likely to have your pull request accepted if it addresses an existing Github issue marked with the good-first-issue tag, these issues are specifically tagged, because they are generally features/bug fixes which can be cleanly merged on a single platform without requiring cross platform work, are generally of lower complexity than larger features and are non contentious, meaning that the core team doesn't need to try and assess the community desire for such a feature before merging.

Of course we encourage community developers to work on ANY issue filed on our Github regardless of how it’s tagged, however if you pick up or create an issue without the “Good first issue” tag it would be best if you leave a comment on the issue so that the core team can give you any guidance required, especially around UI heavy features or issues which require cross platform integration.

Development setup

Tips

Node.js

You'll need a Node.js version which matches our current version. You can check .nvmrc in the dev branch to see what the current version is.

If you use other node versions you might have or need a node version manager.

  • nvm - you can run nvm use in the project directory and it will use the node version specified in .nvmrc.
  • Some node version management tools can read from the .nvmrc file and automatically make the change. If you use asdf you can make a config change to support the .nvmrc file.
  • We use pnpm as our package manager. You can install it by running npm install --global pnpm, but you should read the installation instructions as other methods are better.

Strings & Localization

All user-facing strings are localized and managed via our Localization Platform.

If you are working on a planned feature, you may need to get the latest localized strings. An automated PR will exist to merge these changes into dev, either merge this PR into dev or merge its commit into your branch.

During development you can modify the [ts/localization/locales.ts] and ['ts/localization/english.ts'] files so your changes can be built and tested locally. You must not modify and commit changes to any files in ts/localization/generated/ as they are generated. If your changes require new strings, they can be requested as part of the PR.

Python

You will need a Python version which matches our current version so you can use node-gyp. You can check .tool-versions in the dev branch to see what the current version is.

See node-gyp installation instructions for setting up Python.

Linux

  • Install the required build tools for your operating system

    Debian/Ubuntu

    This will install make, g++, gcc, etc.

    sudo apt install build-essential cmake
    Fedora 
    sudo dnf install make automake gcc gcc-c++ kernel-devel

  • Git setup

    You may need to disable core.autocrlf to prevent line ending issues.

    git config --global core.autocrlf false

  • Install Node.JS

    We recommend using nvm or asdf.

    You can get the current <version> from the .nvmrc.

  • Install pnpm

    The simplest way to do this is via npm, but you should read the installation instructons

    npm install --global pnpm

macOS

  • Install the Xcode Command-Line Tools.

    Optional: Install Homebrew.

  • Install Git.

    We recommend using Homebrew to install Git.

      brew install git

    After installing Git, you may need to disable core.autocrlf to prevent line ending issues.

    git config --global core.autocrlf false

  • Install Node.JS

    We recommend using nvm or asdf.

    You can get the current <version> from the .nvmrc.

  • Install pnpm

    The simplest way to do this is via npm, but you should read the installation instructons

    npm install --global pnpm

Windows

Building on Windows can be a bit tricky. You can set this up manually, but we recommend using Chocolatey to install the necessary dependencies.

The following instructions will install the following:

Setup instructions for Windows using Chocolatey:

Warning

These setup instructions assume a clean system with none of these applications installed. If your machine is already partially set up you may be better off manually installing what you're missing.

  • Open PowerShell as Administrator

  • Install Chocolatey

    Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

Warning

Make sure to read the Chocolatey output for each choco install step. It will tell you if you need to restart your terminal or computer. If you don't do this, you may encounter issues with the next steps.

  • Install Git

    choco install git

Warning

You may need to restart PowerShell for git to be recognized.

After installing Git, you may need to disable core.autocrlf to prevent line ending issues.

git config --global core.autocrlf false

  • Install CMake

    CMake does not add itself to the system path by default, so you'll need specify the ADD_CMAKE_TO_PATH argument.

    choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'

  • Install Visual Studio 2022

    choco install visualstudio2022community

Warning

This next step will likely take a long time. You may need to restart PowerShell for c++ build tools to be recognized.

  • Install Visual C++ build tools workload for Visual Studio 2022

    choco install visualstudio2022-workload-vctools

  • Install Node.js

    If you have multiple node version installed and/or use a node version manager you should install a Node how you normally would.

    If you are using nvm for windows you will need to run nvm install <version> and nvm use <version> as it doesn't support .nvmrc files.

    You can get the current <version> from the .nvmrc.

    choco install nodejs --version <version>

  • Install pnpm

    The simplest way to do this is via npm, but you should read the installation instructons

    npm install --global pnpm

    You'll likely encounter an issue with windows preventing you from running scripts when you run the pnpm command, See: Exclusion Policies. If you do, you can fix it by running the following command:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Build and run

Now, run these commands in your preferred terminal in a good directory for development:

git clone https://github.com/session-foundation/session-desktop.git
cd session-desktop
git submodule update --init --recursive # Initialize and fetch submodules
npm install --global pnpm               # (only if you don’t already have `pnpm`)
pnpm install                            # Install and build dependencies (this will take a while)
pnpm build
# NOTE: on windows you need to use pnpm test-hoisted
pnpm test                               # A good idea to make sure tests run first
pnpm start-prod                         # Start Session!

This will build the project and start the application in production mode.

Troubleshooting

The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I'm aborting now.

This error is caused by the Electron sandbox not being able to run. This is a security feature and not a bug. You can run the application with the --no-sandbox flag to disable this behavior.

pnpm start-prod --no-sandbox   # Start Session!
...(mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64'))...

TLDR If you are using VS Code, check the architecture of your integrated terminal by running uname -m in it. This also applies to NodeJS installations. Check with node -p process.arch. If the architecture doesn't match your host operating system Session will fail to run.

Are you using Visual Studio Code? Make sure that your installation matches your host operating system. For example if your device is arm64 make sure the VS Code installation is not x86_64. If they do not match and you are using VS Code's integrated terminal, it will run on the architecture of the VS Code installation. Therefore if you installed NodeJS or adding packages via the integrated terminal, it will use the wrong architecture and not match your host system. You can check the architecture of your NodeJS installation by running node -p process.arch in the terminal.

This error comes from when you build Session's native modules e.g. better-sqlite3, libsession_util_nodejs, they have been compiled for the wrong cpu architecture.

Hot reloading

More often than not, you'll need to restart the application regularly to see your changes, as there is no automatic restart mechanism for the entire application.

You can keep the developer tools open (View > Toggle Developer Tools) and press Cmd + R (macOS) or Ctrl + R (Windows & Linux) to reload the application frontend.

pnpm watch # this process will keep running until you stop it

Running multiple instances

Since there is no registration restrictions for Session, you can make as many accounts as you want. Each client however has a dedicated storage profile on your machine which is determined by the environment and instance variables.

To run a new instance, you can set the MULTI environment variable to a unique value.

# Terminal A
pnpm start-prod # Start Session!

# Terminal B
MULTI=1 pnpm start-prod # Start another instance of Session!

Storage profile locations

  • Linux ~/.config/
  • macOS ~/Library/Application Support/
  • Windows %AppData%/

This storage profile folder will change directories from [PROFILE_PATH]/Session-{environment} to [PROFILE_PATH]/Session-{environment}{instance}.

For example, running:

# Terminal A
MULTI=alice pnpm start-prod

# Terminal B
MULTI=bob pnpm start-prod

Will run the development environment with the alice and bob instances and thus create separate storage profiles. The storage profiles will be stored at [PROFILE_PATH]/Session-devalice and [PROFILE_PATH]/Session-devbob.

Making changes

So you're in the process of preparing that pull request. Here's how to make that go smoothly.

Testing

Please write tests! Our testing framework is mocha and our assertion library is chai.

The easiest way to run all tests at once is pnpm test. If you are on windows, you'll need to run pnpm test-hoisted.

Commit your changes

Before a commit is accepted the staged changes will be formatted using prettier and linted using eslint. The commit will be reverted if files are formatted or lint errors are returned.

Commit Message Conventions

This project follows Conventional Commits

Commit messages will be checked using husky and commitlint.

Pull requests

So you wanna make a pull request? Please observe the following guidelines.

  • First, make sure that your pnpm ready run passes - it's very similar to what our Continuous Integration servers do to test the app.
  • Never use plain strings right in the source code - all of the user facing strings are managed via our Localization Platform. See Strings & Localization. You must not modify and commit changes to any files in ts/localization/generated/ as they are generated. If your changes require new strings, they can be requested as part of the PR.
  • Please do not submit pull requests for pure translation fixes. Anyone can update the translations via our Localization Platform.
  • Rebase your changes on the latest dev branch, resolving any conflicts. This ensures that your changes will merge cleanly when you open your PR.
  • Be sure to add and run tests!
  • Make sure the diff between dev and your branch contains only the minimal set of changes needed to implement your feature or bug fix. This will make it easier for the person reviewing your code to approve the changes. Please do not submit a PR with commented out code or unfinished features.
  • Avoid meaningless or too-granular commits. If your branch contains commits like the lines of "Oops, reverted this change" or "Just experimenting, will delete this later", please squash or rebase those changes away.
  • Don't have too few commits. If you have a complicated or long lived feature branch, it may make sense to break the changes up into logical atomic chunks to aid in the review process.
  • Provide a well written and nicely formatted commit message. See this link for some tips on formatting. As far as content, try to include in your summary
    1. What you changed
    2. Why this change was made (including git issue # if appropriate)
    3. Any relevant technical details or motivations for your implementation choices that may be helpful to someone reviewing or auditing the commit history in the future. When in doubt, err on the side of a longer commit message.

Above all, spend some time with the repository. Follow the pull request template added to your pull request description automatically. Take a look at recent approved pull requests, see how they did things.

Production Builds

You can build a production binary by running the following:

pnpm build
pnpm build-release

The binaries will be placed inside the release/ folder.

Linux

You can change in package.json "target": "deb", to any of the electron-builder targets to build for another target.

Detailed Build Process

The majority of the codebase is transpiled directly by the TypeScript compiler tsc. Notable exceptions are the workers and svgs, these are built using tsc via webpack.

  1. tsc is run to transpile the majority of the code outputting to dist
  2. Babel bundles the dist JavaScript, compiles the React code with React Compiler and outputs to app
  3. A build script copies all js and non-code source to app.
  4. Webpack is run to build all the workers outputting to dist

Release builds will target app as the source and build from that.

Cached builds

The cache stores hashes of some items to prevent unnecessary copying of unchanged items.

Build process TODOs

  • Minification is unstable and is currently unsupported, there is a WIP script for it minify.js
  • Split babel and react compiler outputs to their own directories and combine their outputs into app. Better for debugging and watching.