Quick start: how Zulip uses Git and GitHub

This quick start provides a brief overview of how Zulip uses Git and GitHub.

Those who are familiar with Git and GitHub should be able to start contributing with these details in mind:

  • We use GitHub for source control and code review. To contribute, fork zulip/zulip (or the appropriate repository, if you are working on something else besides Zulip server) to your own account and then create feature/issue branches. When you’re ready to get feedback, submit a draft pull request. We encourage you to submit draft pull requests early and often.

  • We use a rebase-oriented workflow. We do not use merge commits. This means you should use git fetch followed by git rebase rather than git pull (or you can use git pull --rebase). Also, to prevent pull requests from becoming out of date with the main line of development, you should rebase your feature branch prior to submitting a pull request, and as needed thereafter. If you’re unfamiliar with how to rebase a pull request, read this excellent guide.

    We use this strategy in order to avoid the extra commits that appear when another branch is merged, that clutter the commit history (it’s popular with other large projects such as Django). This makes Zulip’s commit history more readable, but a side effect is that many pull requests we merge will be reported by GitHub’s UI as closed instead of merged, since GitHub has poor support for rebase-oriented workflows.

  • We have a code style guide, a commit message guide, and strive for each commit to be a minimal coherent idea (see commit discipline for details).

  • We provide many tools to help you submit quality code. These include linters, tests, continuous integration and mypy.

  • We use zulipbot to manage our issues and pull requests to create a better GitHub workflow for contributors.

  • We provide some handy Zulip-specific Git scripts for developers to easily do tasks like fetching and rebasing a pull request, cleaning unimportant branches, etc. These reduce the common tasks of testing other contributors’ pull requests to single commands.

Finally, install the Zulip developer environment, and then configure continuous integration for your fork.

The following sections will help you be awesome with Zulip and Git/GitHub in a rebased-based workflow. Read through it if you’re new to Git, to a rebase-based Git workflow, or if you’d like a Git refresher.