ContextQMD
Back to Zammad

Development Workflow

doc/developer_manual/development_environment/development-workflow.md

7.1.14.8 KB
Original Source

Development Workflow

This guide provides reference for the main tasks, scripts, and commands used when developing Zammad.

Rake Tasks & Automation

Zammad provides several Rake tasks to streamline development and setup.

Database Tasks

  • rails zammad:bootstrap:reset - Quickly reset an existing development database
  • rails db:drop zammad:db:init – Reset an existing development database (without running auto_wizard)
  • rails zammad:bootstrap:init – Initializes Database: only run on environment where DB was never set
  • rails db:migrate – Run any pending Rails migrations

Quickly reset an existing development database

[!Tip]

rails zammad:bootstrap:reset is pretty handy when you quickly want to restart fresh without rebuilding the container

One command in few seconds vs multiple clicks around your Docker stack.

It's much faster then rebuilding, but essentially does the same thing.

Explanation

rails zammad:bootstrap:reset:

  • truncates DB
  • migrates it
  • seeds it
  • runs auto_wizard so rails zammad:setup:auto_wizard is not needed afterward
Use it when
  • you want to reset from scratch
  • without removing your data volumes
  • or rebuilding the devcontainer

Initializes Database: only run on environment where DB was never set

[!Caution]

rails zammad:bootstrap:init is mostly not needed for development.

Use rails zammad:bootstrap:init only if you are intending to initialize a previously uninitialized environment like for example production or run on a fresh install.

Package Tasks

  • rails zammad:package:migrate – Run any pending package migrations

System Setup Tasks

  • rails zammad:setup:auto_wizard – Setup system from an auto_wizard definition

Search & Indexing

  • rails zammad:searchindex:rebuild – Full re-creation of all search indexes and re-indexing of all data

Translation Tasks

  • rails generate zammad:translation_catalog – Regenerate the translation catalog
  • rails generate zammad:translation_catalog --full – Update template files from translations
  • rails zammad:translations:sync – Synchronize latest translations from i18n/*.po to the database

Useful Scripts

Zammad includes scripts to streamline common tasks.

Legacy Stack

  • (cd public/assets/images && pnpm install --frozen-lockfile && pnpm exec gulp build) - Regenerate icon assets

New Stack

  • pnpm generate-graphql-api - Regenerate GraphQL introspection file
  • pnpm generate-setting-types - Regenerate Zammad setting types
  • pnpm generate:install - Setup code generation tools
  • pnpm generate:generic-component - Generate generic component
  • pnpm generate:composable - Generate generic composable
  • pnpm generate:store - Generate generic store

Testing

Run tests frequently to verify your changes and avoid regressions.

Setup

Before running tests for the first time, prepare the test database and compile assets:

Further testing:

Linting

Linting ensures consistent code style and readability. They are optional but recommended:

These tools are included in the devcontainer; for manual setups you may want to install them to ensure consistent code style.

Rails Console & Environment Variables

Some tasks can be executed directly via Rails console or rails r:

Import / Enable Features

  • cat filename.eml | rails r 'Channel::Driver::MailStdin.new' - Import an email message as a ticket
  • rails r 'Channel.last.update!(active: true)' - Enable dummy email channel (i.e. from auto_wizard)

Configure System Settings

  • rails r "Setting.set('es_url', 'http://elasticsearch:9200')" - Configure Elasticsearch host
  • rails r "Setting.set('core_workflow_ajax_mode', true)" - Enable Core Workflow AJAX mode
  • rails r "Setting.set('ui_desktop_beta_switch', true)" - Enable Desktop View BETA UI toggle

Manage Packages

  • rails c 'Package.link(%q!/path/to/package/checkout!)' - Link a package
  • rails c 'Package.unlink(%q!/path/to/package!)' - Unlink a package

For further information see:

Further Reading

Learn more about developing and contributing to Zammad: