Skip to content

Latest commit

 

History

History
335 lines (232 loc) · 15.5 KB

DEVELOPMENT.md

File metadata and controls

335 lines (232 loc) · 15.5 KB
Raw

Development

Table of Contents

Click to expand

How to Contribute

Run the Code

While developing the following command will build the app and start electron in debug mode with http cache disabled:

$ pnpm dev

It's also handy to develop in watch mode so that your changes to the code are immediately recompiled. For this you need two terminal windows:

# Terminal 1
$ pnpm -w watch:electron
# Terminal 2
$ pnpm -w start:electron

After making your changes, go in the deltachat/electron Dev-console and press F5 or Cmd+R to reload the frontend process.

Note: this only applies to the frontend code in src/renderer. To build the main process you still need to use pnpm -w build:electron and then restart the deltachat-desktop process. (pnpm -w start:electron)

Code Style

Checking Code Style

The primary command for checking any changes made to the code is:

pnpm -w check

This command in turn splits up into the following commands:

  • pnpm -w check:types -> Runs tsc to make sure the TypeScript code is ok
  • pnpm -w check:lint -> Runs eslint with TypeScript rules to check for common bad practices in all .js, .ts and .tsx files
  • pnpm -w check:format -> Runs Prettier with rules inspired by StandardJS to check formatting in all .scss, .js, .ts, .tsx, .json and .md files
  • pnpm -w check:log-conventions -> checks for illegal use of console.log()

Sometimes eslint complains on code lines that for whatever reason doesn't fit well with the project style. Lines like this can be ignored by using // eslint-disable-next-line on the line prior to the line you would like to ignore:

// eslint-disable-next-line
const unused_var = 'This line would normally trigger some linting errors'

We set up the linting using this guide

If you work with SCSS make sure you read docs/STYLES.md

Running pnpm -w check:lint when using VS Code will make VS Code display the found problems.

If you're unsure it's always safe to run pnpm -w check to check everything. If you know what you're doing you can run the lower level commands for a more fine grained check.

Fixing Code Style

If the code style check fails you can try to have it fixed for you. The primary command for doing this is:

pnpm -w fix

This command in turn splits up into the following commands:

  • pnpm -w fix:lint -> Runs eslint to attempt fixing any issues in all .js, .ts and .tsx files
  • pnpm -w fix:format -> Runs Prettier to attempt fixing formatting in all .scss, .js, .ts, .tsx, .json and .md files

If you're unsure it's always safe to run pnpm -w fix to fix everything. If you know what you're doing you can run the lower level commands for a more fine grained fix.

Tests

Running pnpm -w test runs the unit tests.

E2E testing

see E2E-TESTING.md

Translations

Install the transifex client and get added to the Delta Chat App project.

And periodically we can run the following command to get the new translation strings from translators:

pnpm -w translations:update

When you need to modify language strings do it as a PR on English language strings in the Android repo. It is in a language other than English do it in Transifex.

See the Add experimental language strings section for instructions on how to add new language strings.

Add experimental language strings

⚠ Information on this section might be deprecated. [TODO update this section]

Sometimes you need to add new language strings, but don't want to push them to transifex immediately. Some potential reasons include:

  • the strings may be adjusted in the near future
  • the relevant PR may not get merged
  • you don't have push rights to the transifex language repo

To still be able to implement new language strings, you can add them to the _locales/_untranslated_en.json file. You can also overload every other language string if you need to. The syntax is exactly the same as for all other _locales/*.json files.

Example: {"foobar_desktop": {"message": "This is a test"}}

Tip: run with the --translation-watch flag (included in pnpm start) to start in translation watch mode - which watches the experimental language strings and hot reloads them into dc-desktop on save

Use localized strings in code

There are two methods to use localized strings:

  1. Static usage over window.static_translate
  2. Dynamic usage over i18nContext, where the component that uses this method is automatically rerendered when the user changes the language.
Thumb-rule:
  • in functions like message functions use static_translate
  • in dialog it's generally ok to use static_translate
  • in functional components use the hook/context
  • in classes render functions use <i18nContext.Consumer>{tx=>( )}</i18nContext.Consumer>
  • if you are unsure use static_translate.
Usage:

For the usage please look at existing code, the types and the doc comments.
Generally you just need to know that the <i18nContext.Consumer>, useTranslationFunction() and window.static_translate are the same functions.

CI

For Continuous Integration we use GitHub Actions.

Packaging

Build in production mode (development tools disabled and minified frontend code)

NODE_ENV=production pnpm -w build

# the electron target also has a shortcut that should also work on windows
cd packages/target-electron
pnpm build4production

(for building on Windows you need another command to set the environment variable)

1. Generate Electron-Builder Configuration

First make sure you are in the packages/target-electron dirctory.

Generate the electron-builder.json5 file with pnpm pack:generate_config.

Possible options for pnpm pack:generate_config:

Environment var Effect
NO_ASAR=true Disable asar, used for flatpack

2. Run electron-builder

note: on Windows you need to enable Developer Mode in System settings > For developers before packing

If you haven't done so run pnpm build now.

Then you need to run pnpm pack:patch-node-modules to patch node_modules. (DON'T forget this step!) So that the electron-builder afterPackHook is able to find the rpc binaries.

Start electron-builder:

Command Description
pnpm pack:win Build for Windows (nsis & portable target)
pnpm pack:mac Build for macOS (dmg & mas target)
pnpm pack:linux Build for Linux (AppImage & deb target)
pnpm pack:linux:dir Build for Linux, but just the folder, no package. This is used for Flatpak.

For more info look at the scripts section in package.json.

The commands for windows10 appx and the App Store package for mac are currently not in the scripts section. They are useless for most people anyway, as they require special paid developer accounts or signing certificates.

  • mas - mac appstore build
  • appx - windows appstore build, you can find info on how to build a self-signed appx in APPX_TESTING.md.

If you are building window on windows you might run into the file path limit of 260 characters. To avoid that, make a folder with a short name directly on your drive (like c.tmp).

Release Workflow

See RELEASE.md

Code Structure

Some important folders and files:

├── .gihub/workflows                        # source of our Github Actions
├── CHANGELOG.md                            # what changed
├── RELEASE.md                              # how to make a release
├── _locales                                # translations
│   ├── _languages.json                     # central file which defines the visible languages and their native names for the users to choose
│   ├── _untranslated_en.json               # new translation keys that are not yet upstreamed to the android-repo/transifex.
│   └── ...
├── bin                                     # executable scripts for various developer tasks
├── docs                                    # documentation
├── images                                  # images and icons
├── packages
│   ├── e2e-tests
│   │   ├── [data]                          # possible data dir created by e2e tests
│   │   ├── tests                           # e2e tests executed by playwright
│   ├── frontend                            # the frontend / UI
│   │   ├── bin                             # executable scripts specific to the frontend
│   │   ├── html-dist                       # [generated] output from building
│   │   ├── scss                            # global css stylesheets
│   │   ├── src                             # source code
│   │   ├── static                          # static files that are needed
│   │   └── themes                          # themes
│   ├── runtime
│   │   └── runtime.ts                      # runtime interface that abstracts over runtime, so frontend can run on electron, tauri and browser
│   ├── shared                              # code that is shared between the packages
│   │   ├── shared-types.d.ts               # shared types
│   │   ├── tests                           # tests
│   │   └── ts-compiled-for-tests           # [generated] compiled code for testing
│   ├── target-browser
│   │   ├── runtime-browser                 # runtime implementation for browsers
│   │   ├── static                          # additional pages for login & e2e tests
│   ├── target-electron
│   │   ├── bin                             # executable scripts specific to the electron target
│   │   ├── build                           # scripts and files needed for packaging
│   │   ├── bundle_out                      # [generated] compiled+bundled js code for electron main rocess
│   │   ├── dist                            # [generated] output from packaging
│   │   ├── electron-builder.json5          # [generated] config file for packaging with electron-builder
│   │   ├── html-dist                       # [generated] bundled frontend and static resources
│   │   ├── runtime-electron                # runtime implementation for electron
│   │   ├── src                             # source for electron main process js code
│   │   ├── static                          # static files that are needed
│   │   ├── stub.cjs                        # file that can be used for electron builder to skip signing
│   │   └── tests                           # tests, like a test for the account data migration function
│   └── target-tauri
├── static
│   ├── fonts                               # fonts
│   ├── help                                # help files in different languages, generated by bin/create-local-help.sh
│   └── xdcs                                # internal extension xdcs

Tips for specific subjects

VS Code users

Problem: Strange TypeScript errors that are only visible in VS Code but the project compiles normally

Solution: Tell VS Code to use the workspace version of TypeScript instead of an built-in version more info

URI Schemes on linux

Can only be tested in builds that have a desktop file. The simplest way to do this is to install the appimage generated by pnpm electron-builder --linux AppImage. (Installing with AppImageLauncher)

pnpm cli shell completion

bash:

pnpm completion bash > ~/completion-for-pnpm.bash
echo 'source ~/completion-for-pnpm.bash' >> ~/.bashrc

zsh:

pnpm completion zsh > ~/completion-for-pnpm.zsh
echo 'source ~/completion-for-pnpm.zsh' >> ~/.zshrc

see also: https://pnpm.io/completion

Disable code signing on packaging for macOS

Sometimes you want to package the app for macOS for testing, but don't have the required certificates for signing it. You can set the following environment variable to skip code signing:

export CSC_IDENTITY_AUTO_DISCOVERY=false

Useful Links :

Docs about macOS sandbox permissions:

JSONRPC debug tricks:

If you want to debug how many jsonrpc calls were made you can run exp.printCallCounterResult() in the devConsole when you have debug logging enabled. This can be useful if you want to test your debouncing logic or compare a branch against another branch, to see if your changes reduced overall jsonrpc calls.