Project recommendations on how to organize revision control.

This document is purely advisory. Phabricator works with a variety of revision control strategies, and diverging from the recommendations in this document will not impact your ability to use it for code review and management.

This is my (epriestley’s) personal take on the issue and not necessarily representative of the views of the Phabricator team as a whole.

Overview

There are a few ways to use SVN, a few ways to use Mercurial, and many many many ways to use Git. Particularly with Git, every project does things differently, and all these approaches are valid for small projects. When projects scale, strategies which enforce one idea is one commit are better.

One Idea is One Commit

Choose a strategy where one idea is one commit in the authoritative master/remote version of the repository. Specifically, this means that an entire conceptual changeset (“add a foo widget”) is represented in the remote as exactly one commit (in some form), not a sequence of checkpoint commits.

• In SVN, this means don’t commit until after an idea has been completely written. All reasonable SVN workflows naturally enforce this.
• In Git, this means squashing checkpoint commits as you go (with git commit --amend) or before pushing (with git rebase -i), or having a strict policy where your master/trunk contains only merge commits and each is a merge between the old master and a branch which represents a single idea. Although this preserves the checkpoint commits along the branches, you can view master alone as a series of single-idea commits.
• In Mercurial, it is not generally possible to avoid having ideas spread across multiple commits. Mercurial does not support liberal mutability doctrines (so you can’t squash commits) and does not let you build a default out of only merge commits, so it is not possible to have an authoritative repository where one commit represents one idea in any real sense. Thus, Mercurial is not recommended for projects which may ever need to scale.

Why This Matters

A strategy where one idea is one commit has no real advantage over any other strategy until your repository hits a velocity where it becomes critical. In particular:

• Essentially all operations against the master/remote repository are about ideas, not commits. When one idea is many commits, everything you do is more complicated because you need to figure out which commits represent an idea (“the foo widget is broken, what do I need to revert?”) or what idea is ultimately represented by a commit (“commit af3291029 makes no sense, what goal is this change trying to accomplish?”).
• Release engineering is greatly simplified. Release engineers can pick or drop ideas easily when each idea corresponds to one commit. When an idea is several commits, it becomes easier to accidentally pick or drop half of an idea and end up in a state which is virtually guaranteed to be wrong.
• Automated testing is greatly simplified. If each idea is one commit, you can run automated tests against every commit and test failures indicate a serious problem. If each idea is many commits, most of those commits represent a known broken state of the codebase (e.g., a checkpoint with a syntax error which was fixed in the next checkpoint, or with a half-implemented idea).
• Understanding changes is greatly simplified. You can bisect to a break and identify the entire idea trivially, without fishing forward and backward in the log to identify the extents of the idea. And you can be confident in what you need to revert to remove the entire idea.
• There is no clear value in having checkpoint commits (some of which are guaranteed to be known broken versions of the repository) persist into the remote. Consider a theoretical VCS which automatically creates a checkpoint commit for every keystroke. This VCS would obviously be unusable. But many checkpoint commits aren’t much different, and conceptually represent some relatively arbitrary point in the sequence of keystrokes that went into writing a larger idea. Get rid of them or create an abstraction layer (merge commits) which allows you to ignore them when you are trying to understand the repository in terms of ideas (which is almost always).

All of these become problems only at scale. Facebook pushes dozens of ideas every day and thousands on a weekly basis, and could not do this (at least, not without more people or more errors) without choosing a repository strategy where one idea is one commit.

 

Introduction

How to use Postfix and Fetchmail to access a single Gmail account using an old-fashioned client such as mutt or Emacs GNUS.

If you use Evolution or a similar modern e-mail client, you do not need to use this. Your client has the ability to connect directly to the Gmail POP3 and SMTP services.

• Help with Evolution: UsingGmailWithEvolution.
• Help with Thunderbird: http://mail.google.com/support/bin/answer.py?answer=38343

This setup is intended to be as simple and as close to a standard Ubuntu configuration as possible. This setup does not verify the Gmail SMTP server certificate.

Not For Beginners

You should be familiar with:

• How to install packages
• How to edit text configuration files.
• Terms like POP3, SMTP and SSL.

 

References

• http://prantran.blogspot.com/2007/01/getting-postfix-to-work-on-ubuntu-with.html
• http://souptonuts.sourceforge.net/postfix_tutorial.html
• http://www.postfix.com/TLS_README.html
• http://www.postfix.com/SASL_README.html
• http://www.postfix.com/ADDRESS_REWRITING_README.html
• http://postfix.state-of-mind.de/patrick.koetter/smtpauth/smtp_auth_mailservers.html
• http://postfix.state-of-mind.de/patrick.koetter/smtpauth/postfix_tls_support.html

 

Packages needed

You will need the postfix and fetchmail packages. See InstallingSoftware for more on installing packages. Postfix will work on Ubuntu as is from apt-get without any compilation necessary

 

Setting up your Gmail account

You will need to enable POP access for your Gmail account. This is done through the google website. SeeUsingGmailWithEvolution for more. Gnus queues mail to postfix, postfix forwards to Google. An openssl certificate is made by a CA signing authority signing a request to generate a server-side certificate. Although to encrypt the connection between Gnus and postfix is possible, this is not necessary if mail is being sent from gnus to postix at the local machine. The connection between postfix and google will be encrypted. This is like https but by the smtp protocol which is by emails. So it is not always necessary to use postfix to do this because some A Mail User Agents can do this itselves : a MUA is a client like gnus or evolution. Postfix will be a client when is connects to google, and the variables pertaining by this are beginning as smtp-the-something. Where postfix is the daemon it receives mails, into our case from the localhost, and the variables pertaining by this mode commence as smtpd-something. Don’t forget!

A “mail delivery agent” is the back end used to store mails, which can be postfix. A “mail transfer agent” is a server talking SMTP : it receives mail via SMTP, and it can pass it on via SMTP. Postfix is a combination of MTA and MDA.

to send every mail through Google you also need to set option as

relayhost[smtp.gmail.com]:587

Another option is to use a transport map.

transport_maps = hash:/etc/postfix/transport

The easiest is to just use a mail client, and nothing inter-locuting, but we are not doing this by using postfix at all. Postfix may and can be used as a storage mail retrieval of fetchmail exclusively, and let the mail client perform the smtp encryption to google directly. So this is available as an alternative plan, when this one does work. It is very time-consuming, awkward, frustrating, and annoying.

 

Example username

In all the examples below, I’ve assumed that the username on the Ubuntu system is jane, and that the Gmail username isjane.doe@gmail.com, with password doeadeer. You obviously need to replace these with your local username, your Gmail username and Gmail password as appropriate.

 

Configuring Postfix

To setup Postfix, you will need to create 5 files:

• /etc/postfix/main.cf
• /etc/postfix/generic
• /etc/postfix/generic.db
• /etc/postfix/passwd
• /etc/postfix/passwd.db

You will need root access to create and edit these files; see RootSudo for more on gaining root access.

 

Stop Postfix

It’s not necessary to do so, but if you wish to stop Postfix while configuring, run (as root)

  /etc/init.d/postfix stop

 

/etc/postfix/main.cf

When you install Postfix you will be prompted to make configurative choices. You can choose “No configuration”; in this case noconfiguration file will be created, and you can use the contents below. The configuration choices used to create it are listed in theAppendix.

This is the Postfix configuration file /etc/postfix/main.cf:

 

# See /usr/share/postfix/main.cf.dist for a commented, more complete version

# Debian specific:  Specifying a file name will cause the first
# line of that file to be used as the name.  The Debian default
# is /etc/mailname.
#myorigin = /etc/mailname

smtpd_banner = $myhostname ESMTP $mail_name (Ubuntu)
biff = no

# appending .domain is the MUA's job.
append_dot_mydomain = no

# Uncomment the next line to generate "delayed mail" warnings
#delay_warning_time = 4h

# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
smtpd_use_tls=yes
smtpd_tls_session_cache_database = btree:${queue_directory}/smtpd_scache
smtp_tls_session_cache_database = btree:${queue_directory}/smtp_scache

# See /usr/share/doc/postfix/TLS_README.gz in the postfix-doc package for
# information on enabling SSL in the smtp client.

myhostname = localhost
alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
mydestination = localhost, localhost.localdomain
mynetworks = 127.0.0.0/8
mailbox_size_limit = 0
recipient_delimiter = +
inet_interfaces = loopback-only
inet_protocols = all

##########################################
##### non debconf entries start here #####

##### client TLS parameters #####
smtp_tls_loglevel=1
smtp_tls_security_level=encrypt
smtp_sasl_auth_enable=yes
smtp_sasl_password_maps=hash:/etc/postfix/sasl/passwd
smtp_sasl_security_options = noanonymous

##### map jane@localhost to jane.doe@gmail.com #####
smtp_generic_maps=hash:/etc/postfix/generic

relayhost=[smtp.gmail.com]:587

An explanation of each non-standard line (following the comment “non debconf entries start here”) is given in the Appendix.

 

/etc/postfix/generic and /etc/postfix/generic.db

The generic file tells Postfix how to map local e-mail addresses to Internet addresses when mail is sent via SMTP. Postfix rewrites”From:” headers to make e-mail appear to come from jane.doe@gmail.com instead of jane@localhost.

The /etc/postfix/generic is a plain text file, and should look as follows:

jane@localhost   jane.doe@gmail.com

/etc/postfix/generic.db is generated from this using the postmap command:

cd /etc/postfix
postmap generic

 

/etc/postfix/sasl/passwd and /etc/postfix/sasl/passwd.db

The passwd file contains your Gmail password. Like /etc/postfix/generic file discussed above, it is a plain text file; it should look as follows:

[smtp.gmail.com]:587    jane.doe@gmail.com:doeadeer

To create passwd.db, and set ownership and permissions appropriately, run the following commands:

cd /etc/postfix/sasl
postmap passwd
chown root.root passwd passwd.db
chmod 600 passwd passwd.db

 

Start or reload Postfix

If you previously stopped Postfix, restart it with

  /etc/init.d/postfix start

If you didn’t stop Postfix, force it to reload its configuration with

  postfix reload

 

Testing

Postfix provides a means of testing its address rewriting rules using the sendmail command with the ‘-bv’ option. If the mail would be sent externally (i.e., via smtp.gmail.com), the command will cause sendmail to connect and authenticate to smtp.gmail.com, which makes it a convenient way to test the Postfix setup.

One possibly inconvenient feature of sendmail -bv is that the result is mailed to the user who ran the command; thus, if mail is utterly misconfigured, you will never receive the result. If you suspect this is the case, you can check /var/log/mail.log to see what went wrong, or you can type mail within the same account as the sender.

Alternatively do echo 'test mail' | mail -s 'testing this' foo@bar.com