Development Workflow

Building on from our participate in Rocket.Chat development mode of contribution guide, this guide delves into the specifics of Rocket.Chat's development workflow. It's designed to help you navigate through issue prioritization, the pull request process, and more. Let's dive into the details of contributing effectively to Rocket.Chat.

Issue assignment and responsibility:

We utilize milestones and labels to manage issues asynchronously. Most issues will have labels for at least one of the following:

• Feat ( feat: accessibility, feat: embed, feat: livechat, etc.)

• Subject ( subj: mobile, subj: security, subj: ui/ux, etc.)

• Type ( type: bug, type: new feature, type: discussion, etc.)

Issues that are advantageous to our users and nice-to-haves, but for which we currently lack the resources or priority, are tagged as contrib:, indicating that contributions from the community are welcome to work on them. These issues are classified into easy, intermediate, and experts needed categories. This helps new contributors to select an issue to work on when they join the project, based on the perceived difficulty level of the task associated with the issue.

• Review our labels to identify issues you can address. Indicate your interest, and we'll assign you to the task so you can begin working on it.

To filter very precisely, you could filter all issues for:

• Milestone: Whichever is the current version

• Assignee: Unassigned

• Label: Your label of choice. For instance feat: api, feat: integration / plugin, feat: webrtc, subj: ui/ux, subj: security

• Sort by priority

• You are responsible for the issue you're assigned. If you can't complete it, kindly inform us to have it reassigned or postponed.

Branching and pull requests:

• Create a branch for the feature or fix you are working on.

• You can create a pull request anytime during your development phase. Just make sure you add the label stat: in progress while the PR is not ready for merge and remember to remove the label when it is.

• When naming your pull request, start the name with one of the following tags for identifying changes: [NEW] for new features (eg. [NEW] WhiteBoard integration). [FIX] for bug fixes. You should include the issue number(s) in parentheses whenever possible. (eg. [FIX] OTR timeout problems (#629, #2535)). [BREAK] for giving proper attention to changes that will break previous versions of Rocket.Chat (eg. [BREAK] Change notification setting type from boolean to string)

• Refer to our official guidelines for pull request tags.

Adding changeset to your pull request

A changeset is information about changes made in a branch or commit that will be present in the release's changelog.

Structure of a Changeset

Verb: Start with a verb in the third-person singular present tense.

What: Describe what has been changed

Why: Explain why the change was necessary.

How: Briefly describe how the change was implemented. (Optional)

Example: Verb + What + Why + How

Adjusts (Verb) + the session timeout settings (What) + and updates the authentication middleware (How) + to correctly handle session durations. (Why)

Best Practices

• Use Clear and Descriptive Language: Avoid jargon and be explicit about the changes.

  Instead of: Fixes bug

  Use: Fixes bug causing crash on user profile page load

• Reference Issues and Tickets: Link to related issues or tickets to provide context.

  Example: Closes #123 - Resolves authentication timeout issue

• Keep Commits Small and Focused: Each commit should represent a single logical change.

• Write Meaningful Commit Messages: Follow the same guidelines for writing changesets in your commit messages

• Review and Revise: Before submitting your PR, review your changeset for clarity and completeness.

Getting your pull request reviewed, approved, and merged:

There are a few rules to get your pull request accepted:

• All checks have passed.

• Travis CI runs automatically when you push your pull request. If Travis fails, take a look at the reasons for failure. If it fails for no apparent reason, try running it again.

• You must sign the Contributor License Agreement (CLA).

• At least one team member must approve the pull request.

• Once your code has been deployed in the release-candidate environment, verify that your changes work as intended. We have seen issues where bugs did not appear in development but showed in production due to merge issues.