Contributing¶

Git workflow, commit and merge request conventions for the platform, Easy plugins and RYSes. Branch names and the release flow are in Branch naming conventions.

Start with a task¶

Your work starts with a task in Esko. Pick one from the sprint backlog, assign it to yourself and set the status to Realisation.

Update the task daily with progress and problems. Communicate through task comments, and note there anything you agreed outside the task (for example in a chat).

Repositories¶

Most repositories are in Easy GitLab. A new plugin or RYS may need its own repository. If you cannot access a repository, ask your superior; it is usually a permissions issue.

Branches¶

Create a task branch from the target branch, without tracking it:

git fetch origin
git switch --no-track -c feature/12345_add_dark_mode origin/next/minor

Name branches feature/[TICKET_ID_]description or fix/[TICKET_ID_]description: lowercase ASCII, words separated by underscores, ticket ID omitted when there is none.

Target next/minor for features and fixes. Target next/bugs or master only when explicitly requested (see Branch naming conventions for what each branch is for).

All next/* branches and master are protected. Never push to them directly; deliver through a merge request.

Use one branch per task. When a task spans several repositories, use the same branch name in each of them.

Push with an explicit destination, checking it with a dry run first:

git push --dry-run origin HEAD:refs/heads/feature/12345_add_dark_mode
git push -u origin HEAD:refs/heads/feature/12345_add_dark_mode

Commit messages¶

Use a variant of Conventional Commits with an optional ticket reference at the end:

<type>(<optional-scope>): <description> (refs #1234)

Type	Use for
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation
`style`	Formatting, whitespace
`refactor`	Refactoring without behaviour change
`test`	Adding or updating tests
`chore`	Build process, dependencies, tooling
`perf`	Performance improvements

The scope names the affected component: feat(easy_ai): .... A dotted scope is allowed for more precision: fix(design_system.time_entry_form): ....

Add the reference only when the task is known. Supported formats are (refs #1234), (refs #issue-1234) and (refs #pbi-1234). Several references: (refs #1234, refs #1235). The reference links the merge request to the task in Esko.

feat(easy_ai): add global deactivation button (refs #666352)
fix: resolve end date expiration in cloud (refs #issue-665117)
feat: implement user dashboard (refs #pbi-9146)
chore: clean up dead code

Avoid:

Added new feature (refs #12345)      # missing type
fix: fixed bug (refs #12345)         # vague description
feat: add feature #12345             # wrong reference format

For complex changes add a body:

feat(authentication): implement OAuth2 integration (refs #12345)

- Add OAuth2 provider configuration
- Implement token refresh mechanism
- Update user model to support external auth

Do not use messages like fix, patch or edit. Without a ticket, the description has to be detailed enough for a reviewer reading the log.

Before you commit¶

Run the linters and the tests your change affects. The full suite runs in CI.

bundle exec rubocop <changed.rb>
bundle exec rspec spec/models/user_spec.rb
yarn lint
yarn test path/to/file.test.ts

Do not commit:

credentials, .env files, API keys,
node_modules, local caches, indexed databases (for example the Xapian DB in db/), packages, images and other leftovers from your environment,
IDE files, temporary files, debug code and commented-out code.

Changelogs¶

Every change merged into a RYS, the platform or a plugin needs a changelog entry. With the internal EasyCLI:

easy changelog TYPE --body "my message" --breaking
easy changelog-merge

--body is the entry text, --breaking marks a change that can break other repositories. easy changelog-merge merges the entries when they are ready.

Merge requests¶

Open a merge request when you want feedback. A merge request is reviewed sooner when:

the title uses the commit format (feat(easy_pages): move heading to toggling container title (refs #672697)), not the branch name; without a task, omit the reference,
the assignee is you, and the reviewer is Merge Request Pool (merge_request_pool) or your team,
labels describe the state (Important merge requests are prioritised over WIP ones),
the CI pipeline has passed and QA has tested the change,
the code follows the BE code style or FE code style.

A merge request needs two approvals. See Code review process for the reviewer side.

Suggested description:

## Summary

Brief description of changes

## Changes

- Key change

## Test plan

- [ ] Manual testing performed
- [ ] Unit tests added/updated
- [ ] E2E tests added/updated

## Related issues

refs #12345

When a RYS is integrated into the platform, prepare a merge request in the platform repository as well, updating the RYS version to one compatible with that platform version. A new RYS must be disabled in production; it needs a new Easy plugin with the Gemfile definition.