couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joan Touzet <>
Subject Re: [NOTICE] Updated Bylaws - final readthrough before vote
Date Sat, 19 Jul 2014 22:10:50 GMT
Agree, almost all of the things you mention below for PRs, etc. are policies,
not bylaws. The text in the bylaws should be able to survive even if
we decide to go to the Next Big Thing after git becomes passé.

I am making the change to the bylaws as follows.

Old text
Typically, CouchDB uses the Commit-Then-Review (CTR) model of code collaboration. CTR is lazy
consensus as it is applied to a source code or asset repository. Each change represents a
technical decision made by the committer.

Notification of these changes are sent to the commits mailing list. It is expected that the
rest of the community is regularly reviewing these changes. If a committer wants to object
to a change, they have the option of casting a -1 vote. We call this a veto.

New text
Typically, CouchDB uses the Review-Then-Commit (RTC) model of code collaboration. RTC allows
work to proceed on separate feature or bugfix branches, and requires at least one other developer
to review and approve the changes before they are committed to any shared branch. Additional
details on the code collaboration process are detailed in policy documents outside the scope
of these bylaws.

Notification of these changes are sent to the commits mailing list. It is expected that the
rest of the community is regularly reviewing these changes. If a committer wants to object
to a change that reaches a release branch, they have the option of casting a -1 vote. We call
this a veto.

----- Original Message -----
From: "Alexander Shorin" <>
Sent: Saturday, July 19, 2014 11:02:53 AM
Subject: Re: [NOTICE] Updated Bylaws - final readthrough before vote

On Sat, Jul 19, 2014 at 12:48 PM, Robert Samuel Newson
<> wrote:
> I would like to see a formal change to R-T-C too. I include the useful notes that Cloudant
follows for this model below. Obviously not all this text belongs in the bylaws. I suggest
it, or a variant of it, belongs on our wiki but is referenced in the bylaws, which should
also cover the rules around changing the policy. That is, the bylaws should be able to remain
static while the R-T-C page might evolve over time.
> ---
> We follows a R-T-C protocol for making code changes. Our reviews happen in the form of
Pull Requests on GitHub. Pull Requests (PRs) are a central point of coordination around developing
GitHub and as such we have a well established policy for handling them. This document outlines
the current policies and best practices and each team member is expected to follow them.
> Characteristics of a Good Pull Request
>         • A logical progression of commits
>         • Each commit is a single logical change
>                 • If a commit message says "Also did XYZ while in this code" that's
a strong smell that it should be two commits
>                 • Do not mix logic and style changes in a commit
>                         • Ie, make whitespace changes in their own commit
>         • Feel free to commit often and haphazardly when writing code but use tools
to reorder and rewrite commits before issuing a Pull Request
>                 • Learn how to do interactive rebase
>                 • git add -p is also useful
>         • When responding to Pull Request comments use new commits to address the comments
so that the discussion is kept sane
>         • Before merging a Pull Request when all reviewers have given a thumbs up rewrite
the history of the PR and force push it to GitHub
>         • Pull Requests are a discussion. You don't have to take everything every reviewer
says as a command but you may be asked for a technical argument on why you don't want to make
suggested changes.
> Merging Pull Requests
>         • We use a rough equivalent of Apache Voting system
>         • Generally a +1 is taken to mean the reviewer understands the change, agrees
with the principle behind it, and is confident that it does what is claimed (and only what
is claimed)
>         • Generally speaking, if one or two people +1 a change, feel free to merge
it. It's rare to merge without a single +1
>         • If someone suggests a change to a PR then that blocks the merge until either
the change is made or there's an agreement on why to not make the change
>         • If you suggest a change on a PR it can be helpful to illustrate the level
of care you have for the change
>                 • Style changes are usually low priority (unless they're egregiously
bad violations) so things like "I disagree with this variable name" shouldn't be merge-stopping
issue unless there's a good reason (ie, don't use a variable "count" to store an average)
>                 • Algorithmic changes are generally more important
>                 • Its also perfectly valid to suggest a change with a "Feel free to
ignore this" disclaimer. Gathering reactions to code in the discussion is important even if
we don't act on them
>         • Use the 'merge' button.
>         • Do not merge a branch onto itself.
>         • Never move a tag once made public, burn a version number if you have to instead
>         • Don't delete the topic branch after merge
> ——
> Proper Commit Messages
> First, read
> We pride ourselves on having valuable and useful commit messages. This means that we
adhere to a standard and make use of the various sections of a commit message for tooling
and other automated capturing of our development history.
> Its important to remember that a Git commit message is one of the most permanent things
a developer will create in their day to day activities. If the commit message is not useful
then it is wasting precious opportunity for conveying historical information about the project.
> * Commit messages should reference JIRA tickets
> * Bad commit messages are grounds for veto
> —

Awesome! It would be good to see such guidelines and more of them.


View raw message