Contributing to activist.org

Thank you for contributing to activist!

Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved.

Following this guide helps to communicate that you respect the time of the developers managing and developing this open-source project. In return, and in accordance with this project's code of conduct, other contributors will reciprocate that respect in addressing your issue or assessing patches and features.

If you have questions or would like to communicate with the team, please join us in our public Matrix chat rooms. We'd be happy to hear from you!

First steps as a contributor
Mentorship and growth
Tech stack
Learning the tech stack
Development environment
Style guide
Linting
Testing
Issues and projects
Bug reports
Feature requests
Pull requests
Internationalization
Documentation
Accessibility
Design
Troubleshooting

First steps as a contributor

Thank you for your interest in contributing to activist.org! We look forward to welcoming you to the community and working with you to build a global platform for political action :) The following are some suggested steps for people interested in joining our community:

Please join the public Matrix chat to connect with the community
- Matrix is a network for secure, decentralized communication
- We'd suggest that you use the Element client and Element X for a mobile app
- The General and Development channels would be great places to start!
- Feel free to introduce yourself and tell us what your interests are if you're comfortable :)
Read through this contributing guide and the style guide for all the information you need to contribute
Look into issues marked good first issue and the Projects board to get a better understanding of what you can work on
Check out our public designs on Figma to understand activist's goals and direction
Consider joining our bi-weekly developer sync — new joiners are always welcome!

_{Back to top.}

Mentorship and growth

Onboarding and mentoring new members are integral parts of any healthy open-source community. We need those who are onboarded to gain new skills and take on greater roles of triaging issues, reviewing contributions and maintaining the project. We also need them to help those who follow do the same. Please let us know if you have such goals and we'll work with you to achieve them.

The above includes expectations on the behavior of those who want to grow with us. Mentorship is earned, not given. To be blunt, those who are mainly sending AI generated contributions are not demonstrating an interest in growing their skills and are not helping to develop the project. This is not to say that all uses of AI for contributions are bad, but it should be a tool, not the contributor itself.

Continued constructive contributions, new open issues and communication that provides context for maintainers help them do their work immensely. We would be happy to help such community members expand their skills and take on further responsibilities.

If the above resonates with you, then we look forward to working with you!

_{Back to top.}

Tech stack

The following are the current and planned technologies for activist.org:

Testing

pytest (backend) • Vitest (frontend) • Playwright (end to end)

Localization

Nuxt I18n • Weblate (activist on Weblate)

Analytics

Plausible

Note

Those new to any frameworks or technologies who want to work on their skills are more than welcome to contribute!

_{Back to top.}

Learning the tech stack

activist is very open to contributions from people in the early stages of their coding journey! The following is a select list of documentation pages to help you understand the technologies we use.

Docs for those new to programming

Mozilla Developer Network Learning Area
- Doing MDN sections for HTML, CSS and JavaScript is the best ways to get into web development!
Open Source Guides
- Guides from GitHub about open-source software including how to start and much more!

Frontend tech docs

Backend tech docs

Deployment tech docs

Docker docs

_{Back to top.}

Development environment

Note

Windows users should be aware that Docker development requires Windows Subsystem for Linux (WSL) version 2 or higher. The community would suggest that you clone the repository directly into your WSL environment.

First and foremost, please see the suggested IDE setup in the dropdown below to make sure that your editor is ready for development.

Important

Suggested IDE setup

VS Code

Install the following extensions:

WebStorm

Check out the Vue.js development docs
Make sure a local Node.js interpreter is configured in your project
Make sure the Vue.js plugin and JavaScript Debugger are enabled in the plugins page of the settings

To setup your development environment, first install Docker and Docker Compose.

Note

If you are new to Docker, activist recommends installing Docker Desktop. Docker Desktop comes with many Docker tools and a straightforward user interface.

Fork the activist repo, clone your fork, and configure the remotes:

Note

Consider using SSH

Alternatively to using HTTPS as in the instructions below, consider SSH to interact with GitHub from the terminal. SSH allows you to connect without a user-pass authentication flow.

To run git commands with SSH, remember then to substitute the HTTPS URL, https://github.com/..., with the SSH one, git@github.com:....

e.g. Cloning now becomes git clone git@github.com:<your-username>/activist.git

GitHub also has their documentation on how to Generate a new SSH key 🔑

# Clone your fork of the repo into the current directory.
git clone https://github.com/<your-username>/activist.git
# Navigate to the newly cloned directory.
cd activist
# Assign the original repo to a remote called "upstream".
git remote add upstream https://github.com/activist-org/activist.git

Now, if you run git remote -v you should see two remote repositories named:
- origin (forked repository)
- upstream (activist repository)

Note

First, install uv if you don't already have it by following the official installation guide.

Create a virtual environment for the backend (Python >=3.12), activate it and install dependencies:

cd backend && uv sync --all-extras  # create .venv and install all dependencies from uv.lock

# Unix or macOS:
source .venv/bin/activate

# Windows:
.venv\Scripts\activate.bat  # .venv\Scripts\activate.ps1 (PowerShell)

Start your docker images with the following:

# --build only necessary with new dependencies or backend model changes.
docker compose --env-file .env.dev up --build

# And to stop the containers when you're done working:
docker compose --env-file .env.dev down

You can visit http://localhost:3000/ to see the development frontend once the container is up and running. From there click View organizations or View events to explore the platform.
To view the backend admin UI and Swagger UI, visit http://localhost:8000/admin and http://localhost:8000/v1/schema/swagger-ui/ respectively.
If you'd like to sign in to the frontend via http://localhost:3000/auth/sign-in or the Django admin panel via http://localhost:8000/admin, then you can use the fixtures admin user with the password admin.

Note

Feel free to contact the team in the Development room on Matrix if you're having problems getting your environment setup!

Using Yarn or Python

Dockerized environments are resource intensive - specifically for some Windows users - and may take a very long time to load. If you would like to get just the frontend or backend up and running, please follow the steps below:

Frontend: Yarn

The frontend currently uses Yarn 4.*.

# In the root activist directory:
cd frontend

# Set the environment variables:
set -a && source ../.env.dev && set +a

# Install corepack on your machine globally:
npm install -g corepack

# Install and run the project:
corepack enable
yarn install
yarn run dev:local

You can then visit http://localhost:3000/ to see the development frontend build once the server is up and running.

You can also build the production version locally:

# In activist/frontend:
yarn build:local

# Run the production build:
node .output/server/index.mjs

Backend: Python

Our backend depends on a connection to a postgres DB, therefore we need to setup the database first. Here our best option is to still use docker to create a postgres DB with the following command:

docker compose --env-file .env.dev up db

To run locally, set the environment variable DJANGO_ENV to LOCAL_DEV:

export DJANGO_ENV=LOCAL_DEV

When this is set, django will load environment variables from env.dev first, and then from .env.dev.local which will overwrite some variables for local development.

From here we need the project's dependencies, with the practice being to create a virtual environment first within your local activist directory and then install the dependencies within it:

On Unix or MacOS, run:

cd backend && uv sync --all-extras  # create .venv and install all dependencies from uv.lock

# Unix or macOS:
source .venv/bin/activate

# Windows:
.venv\Scripts\activate.bat  # .venv\Scripts\activate.ps1 (PowerShell)

Now you can apply the database migrations and fixtures, populate it with sample data, and start the local development server.

# In the root activist directory:
cd backend
python manage.py makemigrations
python manage.py migrate
python manage.py runserver
python manage.py loaddata fixtures/superuser.json
python manage.py loaddata fixtures/status_types.json
python manage.py loaddata fixtures/topics.json
python manage.py populate_db \
--users 10 \
--orgs-per-user 1 \
--groups-per-org 1 \
--events-per-org 1 \
--resources-per-entity 2 \
--faq-entries-per-entity 3

You can then visit http://localhost:8000/admin to see the development backend admin UI as well as http://localhost:8000/v1/schema/swagger-ui/ for the Swagger UI once the server is up and running.

_{Back to top.}

Style guide

Please see the activist style guide for details about how to follow the code style for the project. We made this guide to assure that we as a community write clean, cohesive code that's easy to write and review. Suggestions for the style guide are welcome.

_{Back to top.}

Linting

For the backend Ruff is installed via the required packages to assure that errors are reported correctly. We'd also suggest that VS Code users install the Ruff extension.

For the frontend eslint, eslint-vue and vue-a11y are added via the dependencies to provide linting support. eslint-plugin-jsdoc is enabled for function docstring rules in frontend/eslint.config.mjs; whenever those rules apply, follow Frontend JSDoc under Documentation. General comment conventions (sentence style, JSDoc as block comments) also appear under Comments in the style guide.

_{Back to top.}

Testing

Backend

Please run the following commands from the project root to test the backend:

# Format the backend, lint the code and run static type checks:
ruff format ./backend
ruff check ./backend
mypy ./backend --config-file ./backend/pyproject.toml

# Start the Docker container:
docker compose --env-file .env.dev up backend --build -d  # -d to hide logs

# Enter the backend container:
docker exec -it django_backend sh

# Run backend tests:
uv run pytest

# To run a specific test:
uv run pytest path/to/test_file.py::test_function

# To run with a coverage report as is done in PRs:
uv run pytest --cov --cov-report=term-missing --cov-config=pyproject.toml -vv

# Once tests are finished:
exit

Frontend

Static Testing

Please check the formatting of your code using Prettier and run the static type check with eslint before pull requests with the following command:

# Within ./frontend:
yarn install  # necessary for non-Linux users as node_modules are set via Docker
yarn format
yarn lint

You can further run the following commands for TypeScript type checks on the frontend:

# Within ./frontend:
yarn install  # necessary for non-Linux users as node_modules are set via Docker
yarn postinstall  # prepare types in frontend/.nuxt
yarn typecheck

Note

Pre-existing TS errors may be ignored. If you need assistance then feel free to open a PR and we'll support!

Automated Testing

We use Vitest for component and unit testing. You can run the tests with the following command:

# Within ./frontend:
yarn test

If you would like to run a specific test, please run the following command:

yarn test FILE.spec.ts --run

Please see the frontend testing guide for information on how to write component tests.

Note

The Vitest test suite is still in a very early stage. There is a lot of work left to do to increase test coverage, and some features still need troubleshooting. If you need assistance then feel free to open a PR and we'll support!

End to End Testing (E2E)

activist uses Playwright for end to end testing. There are three ways to run the suite locally — pick one:

Recommended: VS Code Playwright extension — single-IDE workflow, no extra shells, easiest for debugging a single test.
Run with run-e2e-tests.sh — one command orchestrates Docker, the frontend preview server, and Playwright.
Run with separate terminals — manual, three-shell flow; use when debugging the environment itself.

Before running tests any way, install (or update) the Playwright browsers. Re-run this each time Playwright is upgraded:

# Within ./frontend:
yarn playwright install --with-deps

See the frontend testing guide for writing E2E tests.

Recommended: Run with the VS Code Playwright extension

Tip

Start here. Using the extension keeps everything in one IDE — you avoid juggling three terminals and can run, debug, and step through a single test with one click.

This path uses the official Playwright Test for VS Code extension (already listed in Suggested IDE setup).

One-time setup

Install the extension above.
From the repo's frontend/ directory, install Playwright browsers once (see prerequisite block above).

Before each run

The extension runs Playwright in your IDE, but it does not start the backend, database, or frontend for you. Start those first:

# 1. Start the backend and database (USE_PREVIEW skips the full build inside Docker):
USE_PREVIEW=true docker compose --env-file .env.dev up backend db -d

# 2. In ./frontend, build and serve the frontend preview (Playwright expects http://localhost:3000):
cd frontend
set -a && . ../.env.dev && set +a
export USE_PREVIEW=true
corepack enable
yarn install
rm -rf dist         # force nuxi preview to use .output/ (node-server)
yarn build:local    # hit 'n' at any install prompts
nohup env NUXT_SESSION_PASSWORD="$NUXT_SESSION_PASSWORD" NUXT_API_SECRET="" \
  node .output/server/index.mjs > /dev/null 2>&1 &

Leave those running in the background. Playwright's globalSetup will create the admin/member auth state on first use and reuse it for up to 20 hours.

Note

You only need to re-run yarn build:local (and restart the nohup node server) after changing frontend source. When you're only editing tests under frontend/test-e2e/, the existing build is fine — just keep the preview server running and re-run tests from VS Code.

Run tests from VS Code

Open the Testing view (beaker icon in the sidebar).
Expand Playwright to see the Desktop Chrome / Mobile Chrome projects.
Click ▶ next to a spec, describe block, or single test to run it; click the bug icon to debug.
Use Show browser in the Playwright panel to run headed, and toggle projects to run desktop-only or mobile-only.

When you're done for the day, stop the background processes:

lsof -ti tcp:3000 | xargs kill -9 2>/dev/null || true
docker compose --env-file .env.dev down

Run with `run-e2e-tests.sh`

Use run-e2e-tests.sh when you want a single command to bring up Docker, build and serve the frontend, run Playwright, and tear everything down. Run from the repository root:

# Note: There may be installation prompts in the build logs. Hit 'n' to say no.
# macOS:
sh run-e2e-tests.sh
# Linux or Windows using WSL:
bash run-e2e-tests.sh

# After the tests finish, view the Playwright HTML report:
cd frontend && yarn playwright show-report

The script accepts a few flags (see ./run-e2e-tests.sh -h for the authoritative list):

Flag	Effect
`-f <path>`	Run a single Playwright spec. `<path>` may be relative to `frontend/` (e.g. `test-e2e/specs/all/landing-page.spec.ts`), prefixed with `frontend/` from the repo root, or absolute.
`-d`	Desktop only (Playwright project `Desktop Chrome`).
`-m`	Mobile only (Playwright project `Mobile Chrome`).
`-s`, `--skip-build`	Reuse the existing `frontend/.output/` build instead of rebuilding. Skips `yarn install` + `yarn build:local` for fast iteration; errors cleanly if no build exists.
`--no-cleanup` (`--keep-up`)	Leave Docker containers (and, on normal exit, the preview server on port 3000) running after the script exits. Handy when debugging failures (inspect the DB, re-run Playwright manually with `--ui`). Prints manual cleanup commands on exit. Caveat: if you abort with Ctrl-C, SIGINT kills the preview server directly; Docker still stays up.
`-h`, `--help`	Print usage and exit without starting Docker or tests.
`-- <args>`	Everything after `--` is forwarded to `npx playwright test` (e.g. `--headed`, `--debug`, `--ui`, `-g "<name>"`, `--repeat-each N`, `--update-snapshots`).

With no -d/-m, both desktop and mobile run (default). Examples:

./run-e2e-tests.sh                                                            # full suite, desktop + mobile
./run-e2e-tests.sh -d                                                         # desktop only
./run-e2e-tests.sh -f test-e2e/specs/all/landing-page.spec.ts                 # one spec, both projects
./run-e2e-tests.sh -f frontend/test-e2e/specs/all/landing-page.spec.ts -m     # one spec, mobile only
./run-e2e-tests.sh -s -f test-e2e/specs/all/landing-page.spec.ts -- --headed  # fast iter, visible browser
./run-e2e-tests.sh -- --grep "qr code"                                        # filter by test name

Tip

The script exits with Playwright's exit code, so ./run-e2e-tests.sh -f … && echo PASS does what you expect.

If you stop the script before it finishes, cleanup is automatic (the script traps EXIT/INT/TERM and tears down Docker + port 3000). If you ever need to tidy up manually:

docker compose --env-file .env.dev down
lsof -ti tcp:3000 | xargs kill -9 2>/dev/null || true

Advanced: Run with separate terminals

Use this path when you need full control (debugging the environment, swapping the preview server for yarn dev:local, running Playwright from a non-VS Code tool, etc.). For most contributors, the extension or the script above is simpler.

In a first shell, start the backend and database:

# Start backend and db (USE_PREVIEW skips the full build inside Docker):
USE_PREVIEW=true docker compose --env-file .env.dev up backend db

In a second shell, build and serve the frontend in preview mode:

cd frontend

# Set the environment variables (bash/zsh can also use `source ../.env.dev`):
set -a && . ../.env.dev && set +a

# USE_PREVIEW=true switches Nitro to node-server preset (outputs to .output/)
# so that `yarn preview` works. Without it the build uses netlify-static (dist/).
export USE_PREVIEW=true

# Install dependencies and build + serve the frontend in preview mode:
corepack enable
yarn install
# Remove any previous static build so nuxi preview uses .output/ not dist/.
rm -rf dist
yarn build:local  # answer no to all package installation prompts
# Note: There may be an installation prompt high in the build logs. Hit 'n' to say no.
# Start the node server directly - this ensures NUXT_SESSION_PASSWORD and NUXT_API_SECRET
# are passed correctly (yarn preview can strip env vars in some shells).
nohup env NUXT_SESSION_PASSWORD="$NUXT_SESSION_PASSWORD" NUXT_API_SECRET="" node .output/server/index.mjs > /dev/null 2>&1 &

In a third shell, run the test suite:

cd frontend

# SKIP_WEBSERVER tells Playwright to reuse the running preview server:
SKIP_WEBSERVER=true yarn test:local

# After the tests finish, run the following to see the Playwright HTML report:
yarn playwright show-report

Thank you for testing locally! ✨

Writing E2E Tests

The frontend testing guide also has a guide for writing E2E tests.

Remote E2E

For testing on your remote forked repository, first create a branch from the remote branch that you want to test against. This can be done with the following command:

git push upstream <local-branch-name>:<remote-branch-name-of-your-choice>

You can then navigate to the remote versions of the actions of the repository in your fork and trigger ci_playwright_e2e.

For maintainers of the activist main repo, testing PRs is done via the following to make sure that origin has a copy of the branch that can be tested against:

# On the branch in question:
git branch  # to find the name of the branch
git push -u origin LOCAL_NAME_OF_BRANCH

You can then visit the actions of the repository to run the the ci_playwright_e2e test against the new branch on origin.

Thank you for testing your PRs! 🎉

_{Back to top.}

Issues and projects

The issue tracker for activist is the preferred channel for bug reports, features requests and submitting pull requests. activist also organizes related issues into projects.

Note

Just because an issue is assigned on GitHub doesn't mean the team isn't open to your contribution! Feel free to write in the issues and we can potentially reassign it to you.

Be sure to check the -next release- and -priority- labels in the issues for those that are most important, as well as those marked good first issue that are tailored for first-time contributors.

Bug reports

A bug is a demonstrable problem that is caused by the code in the repository. Good bug reports are extremely helpful — thank you!

Guidelines for bug reports:

Use the GitHub issue search to check if the issue has already been reported.
Check if the issue has been fixed by trying to reproduce it using the latest main or development branch in the repository.
Isolate the problem to make sure that the code in the repository is definitely responsible for the issue.

Great Bug Reports tend to have:

A quick summary
Steps to reproduce
What you expected would happen
What actually happens
Notes (why this might be happening, things tried that didn't work, etc)

To make the above steps easier, the activist team asks that contributors report bugs using the bug report template, with these issues further being marked with the Bug type.

Again, thank you for your time in reporting issues!

_{Back to top.}

Feature requests

Feature requests are more than welcome! Please take a moment to find out whether your idea fits with the scope and aims of the project. When making a suggestion, provide as much detail and context as possible, and further make clear the degree to which you would like to contribute in its development. Feature requests are marked with the Feature type in the issues.

_{Back to top.}

Pull requests

Good pull requests — patches, improvements and new features — are the foundation of our community making activist. They should remain focused in scope and avoid containing unrelated commits. Note that all contributions to this project will be made under the specified license and should follow the coding indentation and style standards (contact us if unsure).

Please ask first before embarking on any significant pull request (implementing features, refactoring code, etc), otherwise you risk spending a lot of time working on something that the developers might not want to merge into the project. With that being said, major additions are very appreciated!

When making a contribution, adhering to the GitHub flow process is the best way to get your work merged:

If you cloned a while ago, get the latest changes from upstream:
```
git checkout <dev-branch>
git pull upstream <dev-branch>
```
Create a new topic branch (off the main project development branch) to contain your feature, change, or fix:
```
git checkout -b <topic-branch-name>
```

Install prek to ensure that each of your commits is properly checked against our linter and formatters:

# In the project root:
prek install

# Then test the pre-commit hooks to see how it works:
prek run --all-files

Note

prek is Python package that can be installed via pip or any other Python package manager. You can also find it in our uv.lock file.

Note

If you are having issues with prek and want to send along your changes regardless, you can ignore the pre-commit hooks via the following:

git commit --no-verify -m "COMMIT_MESSAGE"

Commit your changes in logical chunks, and please try to adhere to Conventional Commits.

Note

The following are tools and methods to help you write good commit messages ✨

commitlint helps write Conventional Commits
Git's interactive rebase cleans up commits

Locally merge (or rebase) the upstream development branch into your topic branch:
```
git pull --rebase upstream <dev-branch>
```
Push your topic branch up to your fork:
```
git push origin <topic-branch-name>
```
Open a Pull Request with a clear title and description.

Thank you in advance for your contributions!

_{Back to top.}

Documentation

Documentation is an invaluable way to contribute to coding projects as it allows others to more easily understand the project structure and contribute. Issues related to documentation are marked with the documentation label in the issues.

Backend numpydoc docstrings

activist follows numpydoc conventions for documenting functions and Python code.

You can use prek to run the numpydoc docstring linting:

prek run numpydoc-validation --all-files

Function docstrings should have this format:

def example_function(argument: argument_type) -> return_type:
    """
    An example docstring for a function so others understand your work.

    Parameters
    ----------
    argument : argument_type
        Description of your argument.

    Returns
    -------
    return_value : return_type
        Description of your return value.

    Raises
    ------
    ErrorType
        Description of the error and the condition that raises it.
    """

    ...

    return return_value

Frontend JSDoc docstrings

The frontend may enforce docstring documentation on some functions and other symbols using eslint-plugin-jsdoc, configured in frontend/eslint.config.mjs. Run yarn lint from frontend/ to see violations.

When to write JSDoc

Exported composables and shared utils: always add JSDoc.
Local helpers and Vue event handlers: add JSDoc only when the name and types are not self-explanatory.
Vue Props interfaces: one-line comments on fields where useful; skip when the field name and type are obvious.

Explicit directions

Do write one short summary sentence by default. Add a second only when behavior, edge cases, or side effects are not obvious.
Do use @param and @returns when they add something the TypeScript types alone do not.
Do use the format @param name - Description for consistency.
Don't restate TypeScript types in prose (e.g. don't write "takes a string" when the signature says (path: string)).
Don't describe obvious control flow (e.g. "returns true if X, false otherwise" when the return type is boolean and the function name is isX).
Don't repeat the same information in the opening lines, @param, and @returns.
Don't leave empty /** */ blocks.

Examples

One sentence when the signature is clear:

/** Removes leading and trailing slashes from a path segment. */
function normalizePath(path: string): string {

Short prose plus tags when types alone are not enough:

/**
 * Normalizes a router query value to a string array; omits null entries.
 * @param arr - A single value, an array, or undefined from the route query.
 * @returns Possibly empty array of strings.
 */
export function normalizeArrayFromURLQuery(
  arr: LocationQueryValue | LocationQueryValue[] | undefined,
): string[] {

Composable with a short overview and @returns when the return shape matters:

/**
 * Shared app error state, toast on failure, and optional session clear on 401.
 * @returns Reactive `error`, `handleError`, and `clearError`.
 */
export function useAppError() {

Vue Props — one line per field when useful:

export interface Props {
  /** Organizations currently voting in favor. */
  organizations: Organization[];
}

_{Back to top.}

Accessibility

Thank you for your interest in improving activist's accessibility. We want our platform to not only be usable for all people, but also to provide a welcoming environment within the development community for all. This section lists a few points to account for when checking accessibility constraints during development:

Transitions

Users who have motion sickness have the ability to disable transitions and animations on their devices. We use the external dependency reduced-motion to disable transitions and animations in this case.

Tab focusing

Tab focusing sadly doesn't work out of the box for many browsers. Chrome works great, but the following changes are needed for browsers to function properly with tabs. We'll test activist against browsers with these settings with the assumption that people who need tab for more control of the interface will be able to activate them.

Firefox

Go to about:config
Search for accessibility.tabfocus and check that it's set to type Boolean with value true
Remove it and select Number instead
Click on the add button and then enter the value 7

Safari

Go to Keyboard in System Preferences for your computer (assuming it's a Mac)
Select Use keyboard navigation to move focus between controls on Mac OS Catalina or All controls on earlier Mac OS versions
In Safari go to Settings
Go to the Advanced tab
Select Press Tab to highlight each item on a webpage

Once the above steps are finished you should be able to use tab to navigate web pages :)

_{Back to top.}

Internationalization

Weblate

Localization for activist happens on our public localization project on Weblate. Join us there if you'd like to help bring activist to other languages!

To find issues related to localization, please see the localization label in the issues, and to report a localization issue use the localization issue form. Please also see the style guide for more information on how to create new localization keys.

Important

If you're having issues with the vue/nuxt i18n $t local property not being picked up by TypeScript and being reported as invalid/not existing across the codebase, then please add the following file at frontend/types/vue-i18n.d.ts:

// frontend/types/vue-i18n.d.ts
// Attn: Fixes Property '$t' does not exist on type ... errors.
// Note: This file is git ignored, but can be used as a local fix for excessive TypeScript errors.
declare module "vue" {
  interface ComponentCustomProperties {
    $t: (key: string) => string;
  }
}

i18n-check

activist uses i18n-check to validate our internationalization key-value pairs. The basic commands to check the i18n keys and values are:

# Note: You need to have installed the uv.lock file in your virtual environment.
i18n-check -h  # see the help
i18n-check -a  # run all checks

You can also run individual checks. Please see the documentation for i18n-check to learn more.

If you do need to edit the directories and files skipped by certain checks, then these edits can be made in the .i18n-check.yaml file. If you're having issues using i18n-check, please feel free to contact the team for support!

_{Back to top.}

Design

Designs for activist are done in the public design file in Figma. Those interested in helping with activist's design are also welcome to share their ideas using the design improvement template that makes an issue marked with the design label.

Note that the linked Figma file above is the public facing designs. Those interested in improving them or contributing designs for new features are invited to contact the team on GitHub or Matrix. We'd love to see a sample of your work, and if everything looks good we'll schedule a time to get connected!

All branding elements such as logos, icons, colors and fonts should follow those that are set out in activist-org/Organization. As the project is fully open source, these elements are also open for discussion. Your efforts in making activist products professional with a distinct and cohesive identity are much appreciated.

_{Back to top.}

Troubleshooting

Nuxt Auto Import Errors

Nuxt uses auto imports to make frontend development more seamless, but at times these imports malfunction. For the Property 'PROPERTY_NAME' does not exist on type... errors, this is caused both by having an out of sync yarn.lock file and having Nuxt improperly installed.

Please run frontend/reset_local_env.sh to reset the local frontend environment to allow for local testing. This can be done via the following commands in the frontend directory:

```bash
# Linux:
sh reset_local_env.sh

# MacOS:
sh reset_local_env.sh

# Windows:
# Run the commands below found in frontend/reset_local_env.sh.
```

PostgreSQL Port Conflict with PgAdmin or Local PostgreSQL Installation

The Problem

If you have PgAdmin or a local PostgreSQL server installed and it's already listening on port 5432, you may encounter a conflict when trying to run the Docker-based postgres_db service. Docker will fail to bind to port 5432, showing an error like:

Error starting userland proxy: listen tcp4 0.0.0.0:5432: bind: address already in use

Important

Do not change DATABASE_PORT in .env.dev to fix this. Please see details below.

Changing this port will cause test failures, specifically TypeError: can only concatenate str (not "NoneType") to str errors in authentication and serializer tests.

This happens because your app expects PostgreSQL on port 5432. Changing the port in .env.dev breaks database connections during testing.

The Solution

To resolve the port conflict, please stop your local PostgreSQL service instead with one of the following commands:

Linux

sudo systemctl stop postgresql

macOS (Homebrew-based PostgreSQL)

brew services stop postgresql

Windows

Open Services (search "Services" in the Start Menu)
Locate PostgreSQL in the list
Right-click and choose Stop

Once stopped, you can safely run Docker services like the Docker Compose commands in the Development Environment section.

Still experiencing problems?

Please feel free to reach out to the team in the Development room on Matrix if you have a question!

_{Back to top.}

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to activist.org

Contents

First steps as a contributor

Mentorship and growth

Tech stack

Frontend

Backend

Deployment

Testing

Localization

Analytics

Learning the tech stack

Development environment

Using Yarn or Python

Style guide

Linting

Testing

Backend

Frontend

Static Testing

Automated Testing

End to End Testing (E2E)

Recommended: Run with the VS Code Playwright extension

Run with run-e2e-tests.sh

Advanced: Run with separate terminals

Writing E2E Tests

Remote E2E

Issues and projects

Bug reports

Feature requests

Pull requests

Documentation

Backend numpydoc docstrings

Frontend JSDoc docstrings

When to write JSDoc

Explicit directions

Examples

Accessibility

Transitions

Tab focusing

Internationalization

Weblate

i18n-check

Design

Troubleshooting

Nuxt Auto Import Errors

PostgreSQL Port Conflict with PgAdmin or Local PostgreSQL Installation

The Problem

The Solution

Still experiencing problems?

Run with `run-e2e-tests.sh`