Skip to content

Latest commit

 

History

History
208 lines (147 loc) · 9.27 KB

CONTRIBUTING.md

File metadata and controls

208 lines (147 loc) · 9.27 KB
Raw

Contributing to Ferdium 6

🎉 First off, thanks for taking the time and your effort to make Ferdium better! 🎉

Table of contents

Code of Conduct

This project and everyone participating in it is governed by the Ferdium Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to hello@ferdium.org.

What should I know before I get started?

For the moment, Ferdium's development is only starting, aiming at releasing a 6.0.0 version with the rebranded assets and tooling upgrade completed. You can join our official Discord chat to get more updates and discuss issues with the other contributors.

How can I contribute?

As a basic rule, before filing issues, feature requests or anything else : take a look at the existing issues and check if this has not already been reported by another user. If so, engage in the already existing discussion.

Setting up your development machine

Install system-level dependencies

Note: This list can likely get outdated. If so, please refer to the specific version of the electronuserland builder that we use in our Dockerfile.

Node.js, pnpm

Please make sure you are conforming to the engines requirements used by the developers/contributors as specified in the package.json and recipes/package.json files.

Currently, these are the combinations of system dependencies that work for MacOS/Linux/Windows. Versions are pinned down to the patch number so ensure you have the exact matching versions installed and in use.

# Note: 'jq' is not a required system dependency; its only here to show the combined output of versions needed
$ jq --null-input '[inputs.engines] | add' < ./package.json < ./recipes/package.json
{
  "node": "20.12.2",
  "pnpm": "8.15.7"
}

Note: You can choose any version manager to manage multiple versions of node and pnpm. For eg, nvm or asdf.

Git

The version 2.23.0 for Git is working fine for development. You can then use the console from Git to do the development procedure.

On Debian/Ubuntu

apt-get update -y && apt-get install --no-install-recommends -y rpm ruby gem && gem install fpm --no-ri --no-rdoc --no-document

On Fedora

dnf install libX11-devel libXext-devel libXScrnSaver-devel libxkbfile-devel rpm

On Windows

Please make sure you have the following installed:

  • Microsoft Visual Studio Build Tools (2017, 2019 or 2022 - with Windows 10 SDK selected).

Clone repository with submodule

git clone https://github.com/ferdium/ferdium-app.git
cd ferdium-app
git submodule update --init --recursive --remote --rebase --force

It is important you execute the last command to get the required submodule (ferdium-recipes).

Run the script

Run the following script to install all dependencies, and build Ferdium.

# On Unix
./scripts/build-unix.sh

# On Windows Powershell
.\scripts\build-windows.ps1

Assets will be available in the out folder.

If you encounter the gyp: No Xcode or CLT version error on macOS at this step, please have a look here.

Using Docker to build a linux-targetted packaged app (not supported as a 1st-class citizen)

docker build -t ferdium-package-`uname -m` .

The above will place all the built artifacts into the /ferdium folder within the image.

If you want to copy them outside of the image, simply mount a volume into a different location, and copy all files from /ferdium into the mounted folder (/ferdium-out in the example command below).

DATE=`date +"%Y-%b-%d-%H-%M"`
mkdir -p ~/Downloads/$DATE
docker run -e GIT_SHA=`git rev-parse --short HEAD` -v ~/Downloads/$DATE:/ferdium-out -it ferdium-package-`uname -m` sh
# inside the container:
mv /ferdium/Ferdium-*.AppImage /ferdium-out/Ferdium-$GIT_SHA.AppImage
mv /ferdium/ferdium-*.tar.gz /ferdium-out/Ferdium-$GIT_SHA.tar.gz
mv /ferdium/ferdium-*.x86_64.rpm /ferdium-out/Ferdium-x86_64-$GIT_SHA.rpm
mv /ferdium/ferdium_*_amd64.deb /ferdium-out/Ferdium-amd64-$GIT_SHA.deb
mv /ferdium/ferdium-*.freebsd /ferdium-out/Ferdium-$GIT_SHA.freebsd
mv /ferdium/ferdium /ferdium-out/Ferdium-$GIT_SHA
mv /ferdium/latest-linux.yml /ferdium-out/latest-linux-$GIT_SHA.yml

Start development app

Run this command on the terminal:

pnpm debug

Note: please prefer debug() over console.log(). However, due to an Electron bug, using require('debug') directly is dangerous and can lead to data loss in services. Please use the src/preload-safe-debug module instead until the bug gets fixed.

Styleguide

Git Commit Messages format

  • Use the present tense ("Add feature" not "Added feature")
  • Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
  • Limit the first line to 72 characters or less
  • Reference issues and pull requests liberally after the first line
  • When only changing documentation, include [ci skip] in the commit description

Javascript Coding style-checker

  • Please use prettier and the defined rules to maintain a consistent style

Code Signing on a mac (not necessary in the normal circumstances)

If you want to self-sign on a mac with non-registered certificate (not for distribution of the resulting package), you can follow this thread and run this command:

codesign --deep --force --verbose --sign - node_modules/electron/dist/Electron.app

Release

git checkout nightly && git pull -r
git checkout release
git merge --no-ff nightly --no-verify
# <manually resolve conflicts>
# <manually bump version with 'beta' name (if beta) in `package.json`>
# <run the build script for your OS from the `scripts` folder>
# <add all pertinent changes to git>
# <create commit>
git push upstream release
# Note: Do NOT allow the GHA release process to create the tag automatically, since that will be at the SHA in the develop branch and not on the release branch - which is logically incorrect
git tag v$(node -p 'require("./package.json").version')
git push upstream --tags
# Note: GHA will automatically build with publish since its the release branch
# Note: Once the GHA action is completed, verify the builds (there should be 32 assets before publishing)
gco develop
# <If its a public release, manually bump to next nightly.0 version in package.json>
# <If its a public release, manually fix homebrew-ferdium PR>

This will automatically trigger the build, as part of which, a new, draft release will be created here. Once all the assets are uploaded (19 assets in total), publish the release (you will need elevated permissions in GitHub for doing this). The last commit of the release branch will be tagged.

Nightly releases

Nightly releases are automatically triggered every day (details) and available in ferdium/ferdium. Maintainers still need to verify and manually publish the draft releases as pre-releases for now.

Updating the code after a hiatus

Since we are making a lot of changes that involve restructuring the code as well as taking a hard look at the dependencies (including node versions), please remember to update them by running the appropriate command of your chosen package manager.