Deployment Practices

Distribution Types

Single-file source

Description
A single file encompasses a program (or library code)
Examples
Advantages
  • can be run through the web: for python, bash, and any interpreter that accepts stdin or (in bash) a file, you can run scripts over (e.g.) HTTP if they have a canonical URL: 
      curl http://example.com/script/location | python - [arguments]
    Alternatively, as a file (in bash): 
      python <(curl http://example.com/script/location) [arguments]
Disadvantages
  • Particularly for library code, you have to put this in the right place and/or there may be other setup involved. While certain deployment strategies may automate this, when trying to duplicate by hand this may be problematic, causing frustration and wasted hours on new-comers to the project (veterans will have already memorized this bit of esoterica, albeit they may only have random recall in a practicable fashion). In general, when a file is a standalone, it should go out of its way to do the necessary setup necessary internal to the file.

Single + Generated File

Description
you have a single file "distribution" that is generated from upstream files
Reference
templates

Single File Python Package

Use case
A (python) module must be a setuptools package, but it must be a single file to aid in synchronization
Recipe
call setuptools.setup wihtin the file itself (e.g. with a command line option). keep in a repository next to a stub setup.py that invokes the module's setup function for pypi and easy_install compatability.
Example
ManifestDestiny is a single-file package that is setup-able: http://hg.mozilla.org/automation/ManifestDestiny

Synchronization

Version Control Systems

SVN

strengths
  • inherent subrepositories: unlike DVCS, subversion (and CVS) version recursively per-directory. This makes synchronization easier
  • svn:externals: you can include other repositories in your checkouts! but they must must be SVN (is this true?)
weaknesses
  • not distributed

mercurial

advantages
  • hg subrepos

git

disadvantages
  • no prescribable workflow: while VCS and workflow should be separate constituents, unfortunately neither git nor github has tackled the workflow side of the issue. Without the ability to specify a workflow, there is a severe lack of automation for several people working on the repository

Going from one distribution type to another

As discussed, it is often the case where there are multiple distribution types for various needs. One example is JS libraries: usually, in order to limit bandwidth and for ease or portability, a JS library is usually a single file with no extra whitespace. However, it is usually developed in a form more friendly to read. Various distributions for a project should generally be generated from one canonical source.