Skip to content

external contributor guidelines

Jump to bottom
Gordon Tillman edited this page Jan 19, 2018 · 1 revision

External Contributor Guidelines (DRAFT)

Introduction

These guidelines are intended for use by external parties who are interested in making code contributions to the Zimbra Open Source Collaboration product. Synacor launched the Zimbra Open Source project at the March 2017 Zimbra Commit Event. As part of the preparations for that event, the FOSS code base was migrated to the Zimbra organization on GitHub.

Any references to ZCS that follow in this document should be understood to mean Zimbra Collaboration Suite, Open Source (aka FOSS) Edition.

Getting Started

The easiest way to get started with developing for ZCS it to take advantage of our pre-configured Docker image docker-zcs-dev-machine. Full instructions are in the README.

Some additional notes related to setting up Eclipse or IntelliJ may be found here.

Repository Conventions

Our internal developers for ZCS follow a slightly-modified version of GitFlow when working with the various repositories that, taken together, comprise ZCS.

In GitFlow, each repository has two permanent branches:

  • master
  • develop

The HEAD of master always represents the current product release. The HEAD of develop represents the next potential product release.

Internally, we primarily work in bugfix or feature branches that are based on develop and are merged back into develop when they have been completed. There are a few other branching scenarios and the GitFlow link above talks about them in more detail.

The main additional requirement that we enforce in addition to standard GitFlow practices is that bugfix and feature branches must be freshly rebased before merging them back into their base branch. The following illustration shows this rebase requirement.

Revised Branching Model

As an External Contributor

As an external contributor, you will have to work from your own forks of the ZCS repositories that you need. A general overview of the process would be as follows:

  1. Fork the repository that you are working with.

  2. Clone your fork to an appropriate directory on your development machine.

  3. Create a branch to work with. In most cases you will base your branch off of origin/develop. It is a good idea to include the ticket number in your branch name.

  4. Make your changes, being sure to organize your work and your commits so that they are understandable to reviewers.

  5. Write good commit log messages.

    • The first line of the commit message should be short!

    • If you are working against a Bugzilla or Jira ticket, start the first line of your commit message with the ticket number.

    • Where applicable, include additional information in the commit message as follows:

      <ticket #> first line of commit message

      Additional information. Note one blank line between the the first line of the commit message and this additional information.

  6. Include tests when possible and applicable.

  7. Separate non-functional changes (white space, etc) from functional changes. For example, when you are working on an existing file and you see some formatting or other non-functional changes that need to be made, make those changes first, save the file, and commit that change. Be sure that the first line of the commit message indicates that it is a non-functional change. Example:

     <ticket #> noop - whitespace changes

  8. Before pushing your branch back to your fork and submitting a pull request, take a minute to reorganize your commits if necessary. For example, if you have multiple commits with non-functional changes, it is best to do an interactive rebase, put all of the non-functional change commits first, and even squash them up into a single commit.

  9. Run the applicable unit tests and SOAP tests to make sure your changes have not introduced a regression.

  10. Before pushing your branch back to your fork, make sure your pull request branch is still based on the HEAD of the base branch.

  11. After pushing your branch back to your fork, submit a pull request against the appropriate repo and branch (usually develop) in the Zimbra organization.

  12. Write clear and detailed pull request documentation. Be sure and reference applicable ticket numbers.

After you submit the pull request...

  1. You will be asked to digitally sign the CLA (Contributor License Agreement). This must be done before we can review your pull request.
  2. Watch for feedback from Zimbra developers.
  3. If your pull request is approved, we will not merge it via the Merge button on the pull request page. An internal bugfix or feature branch will be created that includes all of your pull request commits. If necessary, it will be rebased on the HEAD of the base branch. If your pull request contains a single commit, it will be merged inline, without creating an empty merge commit. That would serve no purpose. If your pull request contains multiple commits, they will be merged using the --no-ff flag so that a merge commit is created.
  4. At that point the individual who merged your pull request will close the pull request, including a comment to indicate the pull request branch has been merged.
  5. You should then delete your local pull request branch and the pull request branch in your fork. Please create a new branch for future work.

Miscellaneous Resources

Clone this wiki locally