Contributing
This guide outlines a clear, streamlined process for making meaningful contributions with minimal friction and maximum clarity.
Overview
Please Do
- Check if there is an existing issue before submitting a new one
- Open an issue if:
- Something isn’t working as expected
- You’re proposing a significant change
- You’re suggesting a new feature
- Open a merge request (MR) to:
- Implement a change discussed in an issue (link the related issue)
In general, open an issue before submitting a merge request. It improves visibility, avoids duplicate work, and allows early feedback.
Please Don’t
- Submit large or complex changes without opening an issue first
- Push directly to the main branch
- Combine unrelated changes in a single MR — keep it focused
Communication Guidelines
Follow our Engineering Communication standards for MR discussions, team updates, and documentation practices.
1. Create an Issue
- Always assign two labels to the issue (issue type and issue scope)
Issue Labels
- type: bug
- type: enhancement
- type: documentation
- scope: design
- scope: frontend
- scope: backend
- good-first-issue
| Label | Description | Example Usage |
|---|---|---|
| type:bug | Broken or incorrect functionality that deviates from expected behavior. | Submit button doesn’t work on mobile, layout shifts on scroll, API returns 500 |
| type:enhancement | A new capability or an improvement to existing functionality or structure. | Refine sidebar animation, improve search UX, optimize script loading |
| type:documentation | Involves updating docs, READMEs, onboarding guides, or code comments. | Add theme setup instructions, clarify environment config steps |
| scope:frontend | Related to client-side logic, UI components, or browser rendering. | Fix mobile nav, implement tabbed layout, improve accessibility on modals |
| scope:backend | Related to APIs, server logic, data flow, or business logic. | Add caching to REST endpoints, fix login logic, sync newsletter queue |
| scope:design | Requires design input or tasks related to visual or UX decisions. | Create layout for new landing page, adjust spacing system, review icon styles |
| good first issue | Simple, well-scoped task ideal for onboarding or new contributors. | Fix a typo in docs, update footer links, change button color in theme CSS |
Format & Example
Issue Title
Keep issue title concise (ideally under 10 words)
Add contributing document to the engineering-playbook
Issue Label
type: documentationscope: backend
2. Create a Branch
- Use a prefix that reflects the type of work
- Use hyphenated lowercase names with a maximum of 3 words
- One branch per issue
Branch Prefix
- fix/ (hotfix/)
- feat/
- docs/
| Issue Type | Branch Prefix | Example Branch Name |
|---|---|---|
| type: bug | fix/ | fix/3-issue-approach-description |
| type: enhancement | feat/ | feat/9-issue-approach-description |
| type: documentation | docs/ | docs/1-issue-approach-description |
Format & Example
prefix/issue#-description(approach)
docs/2-add-contributing-document
3. Commit Message
- Use only lowercase
- Write atomic commits — one change per commit
- Commit message should describe what the change does, not just what file/branch it belongs to
- Commit Scope (what part of the project is affected): To provide additional contextual information about the change
Commit Scope
- repo – Root of the repository
- wordpress – Changes to the WordPress folder
- api – Backend API-related changes
- style – UI/UX or CSS-related updates
- etc.
| Element | Think of it as… | Example |
|---|---|---|
| type | What kind of change it is | feat, fix, chore, docs, etc. |
| scope | Where the change happened | auth, ui, .gitlab, wordpress, repo |
| message | What you did | update button text, add issue templates |
| Commit Message | What it means |
|---|---|
| fix(ui): fix misaligned login button | You fixed a bug in the UI |
| feat(auth): add 2FA support | You added a new feature in the auth area |
| docs(wordpress): update theme setup guide | You updated documentation for WordPress |
| chore(.gitlab): add issue templates | You did a maintenance/config task in the .gitlab folder |
| style(theme): adjust padding on hero section | You changed styling in the theme code |
| refactor(seo): simplify metadata injection | You cleaned up or restructured SEO code |
Format & Example
type(scope): description
docs(repo): add contributing documentdocs(repo): include all four sections in contributing documentdocs(repo): update contributing document
4. Submit a Merge Request
- After commiting all changes, push the feature branch to the remote repository
- Open a Merge Request into main
MR Title
- Summarize the overall purpose of the merge request by combining the intent of all related commits
- Treat the MR title as a consolidated commit message
MR Description
- Use the MR template for consistency
- List summary of all changes in bullet points
- Reference issues in the “Related Issues” section
Format & Example
MR Title
docs(contributing): add contributing document
MR Description
- Fixed header layout issues on mobile screens- Refactored layout styles for reusability
Related Issues
Issue #14
Before submitting, please follow our Git Merge and Rebase Workflow Guide to keep the commit history clean and up-to-date with the base branch.
Code Traceability
To maintain a clear and linear history, we follow these principles:
- We aim for a clean, linear commit history by using squash merges without separate merge commits.
- Every commit to the main branch must be made via a Merge Request (MR).
- Every issue should have a corresponding Merge Request and a dedicated branch. This ensures full traceability from issue to code.