Zetkin

This is the new Zetkin front-end application, currently under development. It will run at app.zetkin.org and replace the current www.zetk.in, call.zetk.in and organize.zetk.in applications.

NOTE: This is extremely early stages of development. The plan is to launch a public beta in the spring of 2023.

Technology

The new Zetkin app is built on NEXT.js with TypeScript.

Development

Install all the dependencies using yarn (Classic):

$ yarn install

Then start the devserver:

$ yarn devserver

You should now be able to access the app on http://localhost:3000. It will communicate with the Zetkin API running on our public development server.

Integration tests

Integration tests are run with Playwright. To run tests:

yarn playwright

This will also build the next.js application. You can save time and not rebuild the application (if only working on tests, for example), using:

yarn playwright:skipbuild

Unit tests

Unit tests are run on functions and on components when we don't need to test component integrations. We use Jest with @testing-library/react. To run unit tests:

yarn test // To run tests once.

yarn test --verbose // Include this flag to always include console.log output.

yarn test --watchAll // To run tests in interactive watch mode.

We override the default render() function from @testing-library/react in the file src/test-utils/index.ts in order to automatically apply context providers. All @testing-library/react functions are exposed from the custom test-utils module, so import from there instead of @testing-library/react.

import { render, fireEvent } from 'test-utils';

/// Then use render as is documented in the docs for @testing-library/react.

The react-intl setup in tests does not render the text in the components and instead renders the i18n string id. When attempting to target strings in tests, search for the id that you expect, not the translated text.

Development server login credentials

You can log in using the dummy user accounts to access dummy data from the development server.

Hint: when in doubt, use Administrator

Role/access	Username	Password	SMS code
Administrator	[email protected]	password	999999
Caller	[email protected]	password	999999
Basic user	[email protected]	password	999999

The SMS one-time password is only required in some parts of the app.

Contributing

This repository has an .editorconfig file which can automatically configure your editor to the correct style. Make sure your editor supports .editorconfig files, or install a plugin.

The CI server will run eslint and typescript to verify type safety and code style. You can run the linter yourself like this:

$ yarn lint

To avoid commiting anything that breaks linting rules, you can set up a git pre-commit hook. The .githooks/ directory contains such a hook, so the easiest way to set it up is to just configure git to use hooks from there:

$ git config core.hooksPath .githooks

Handling UI text strings

The Zetkin codebase is internationalized and is continuously translated to multiple languages. For that purpose, we never use statically defined ("hard-coded") strings in UI components.

Localized strings are called "messages" and are defined in messageIds modules that exist for all features (e.g. src/features/surveys/l01n/messageIds.ts) and the ZUI design system components (src/zui/l10n/messageIds.ts). The messages have an ID derived from their object structure, and a default (English) string.

If you want to add a new string, add it to the relevant messageIds module.

Translations are stored in YAML files in src/locale. These files are not created by humans. The English "translations" are generated from the messageIds, and any other language is generated by our translation interface.

When the GUI is rendered, translations take precedence. This means that if you want to change a string that already exists, you need to update it in messageIds and then re-generate the English YAML file. You can do that with yarn make-yaml.

Changes to the YAML files should only ever happen using yarn make-yaml, and should be included in pull requests.

More information about how our internationalization system works can be found in the PR that introduced it.

Code formatting

The linting script also runs Prettier so make sure you run Prettier before you commit, or your work won't pass CI. Some IDEs support Prettier as standard and for some you need to download a plugin.

For VSCode, install the plugin, then

• Go to extension settings / workspace and set Prettier: Config Path to ".prettierrc.json"
• Set Prettier: Ignore Path to ".prettierignore"
• Check the box next to Prettier: Require Config
• Uncheck the box next to Prettier: Use Editor Config
• Go to Settings / Text Editor and change the Editor: Default Formatter to "Prettier"
• Go to Settings / Text Editor / Formatting and check Editor: Format On Save

Submit your contribution

If you don't yet have write access to the repository, you can create a fork on your own GitHub and work there.

Pick an issue from the list and write a short message on the issue to let us know that you intened to work on it.

Create a git branch for your work named issue-<number>/some-description, e.g. issue-99/event-component for issue #99.

As a general style, we write our commit messages as short sentences in imperative mood, e.g. "Add MyList component" rather than "Added MyList component".

When you're ready, create a pull request and expect it to be reviewed within a few days.