Skip to main content

First contribution

New contributors who write code—welcome. This page is for code Merge Requests (Ruby, and docs-in-repo that need CI). Others start at Ways to contribute.

Work is tracked as issues on GitLab.

tip

First time here? Pick a small or welcoming issue, leave a short comment that you are taking it, then open a Merge Request against that issue.

Conduct and license: repository CONTRIBUTING.md. Docs site: Overview.

Two ways to open a Merge Request​

You can change the project in either of these ways (they are not mutually exclusive):

  1. GitLab web UI — edit in the browser, propose a Merge Request.
  2. Git CLI — clone your fork, branch, push, open a Merge Request.

Both end the same way: a Merge Request on the upstream project for review.

Using the GitLab web UI​

  1. Fork the project into your GitLab namespace.
  2. On your fork, create a feature branch from an up-to-date main. Never commit on main.
  3. Edit the files you need, commit on that branch.
  4. Open a Merge Request from your branch into upstream main. Link the related issue.
  5. Address review comments; when merged, delete the feature branch on your fork.

If you are fixing a reported issue, comment on the issue so others know it is taken.

Using Git on the command line​

  1. Fork the project on GitLab (same as above).
  2. Clone your fork, then add the upstream remote:
git remote add upstream https://git.octree.ch/decidim/vocacity/decidim-modules/decidim-module-rest_full.git
  1. Sync main from upstream (fetch + merge or rebase), then create a feature branch.
  2. Commit your work on that branch (see Commits).
  3. Push the branch to your fork and open a Merge Request into upstream main.
  4. After merge, delete the local and remote feature branch; keep main aligned with upstream.

Verify before opening a Merge Request​

Before you open a Merge Request, run the same checks as CI: Compose service rest_full, then ./bin/check from the module root inside the container. On a fresh clone, run bin/setup-tests once first (it builds the gitignored dummy app—do not commit that tree).

docker compose up -d
docker compose exec rest_full bash -lc 'cd /home/module && ./bin/check'

Appraisals (Decidim 0.32 + 0.29 + apartment)​

GitLab RSpec jobs are hardcoded to BUNDLE_GEMFILE=gemfiles/decidim_0.32.gemfile (Ruby 3.4) and gemfiles/decidim_0.29.gemfile (Ruby 3.2). Default Compose image / OpenAPI generation stay on 0.32. An extra appraisal (gemfiles/decidim_0.32_apartment.gemfile) pins decidim-apartment + ros-apartment 3.4.4 for tenant-schema compatibility; it is not on the default Gemfile and is not a GitLab job. Run it locally with BUNDLE_GEMFILE (below).

Migrations differ between minors. bin/setup-tests stores spec/decidim_dummy_app/.decidim_appraisal (decidim-0.29 / decidim-0.32 / decidim-0.32-apartment) and regenerates test_app + drops the test DB when that key changes. Same-appraisal re-runs only migrate.

# Install lockfiles (inside rest_full for 0.32; use ruby:3.2 for 0.29)
bundle exec appraisal install

BUNDLE_GEMFILE=gemfiles/decidim_0.32.gemfile bin/setup-tests
BUNDLE_GEMFILE=gemfiles/decidim_0.32.gemfile bundle exec rspec

BUNDLE_GEMFILE=gemfiles/decidim_0.32_apartment.gemfile bin/setup-tests
BUNDLE_GEMFILE=gemfiles/decidim_0.32_apartment.gemfile bundle exec rspec

# Switching minor rebuilds the dummy automatically (no FORCE_SETUP_TESTS needed)
BUNDLE_GEMFILE=gemfiles/decidim_0.29.gemfile bin/setup-tests
BUNDLE_GEMFILE=gemfiles/decidim_0.29.gemfile bundle exec rspec

yarn gen:openapi-spec / bin/swaggerize always pin gemfiles/decidim_0.32.gemfile and refuse 0.29.

Commits​

Use Conventional Commits. Prefer yarn commit (Commitizen) so the message format stays consistent for changelog and releases.

What to change​

Do not invent architecture here—follow the existing docs:

TopicPage
How the API is builtCore concepts
How the project and CI are structuredArchitecture
Adding an HTTP endpointRecipe
How to installInstallation

Further reading​