Source Repository Layout Architecture Considerations

  • strict warning: Non-static method view::load() should not be called statically in /hermes/walnaweb12a/b57/moo.greydragoncom/nodsw/sites/all/modules/views/views.module on line 906.
  • strict warning: Declaration of views_handler_argument::init() should be compatible with views_handler::init(&$view, $options) in /hermes/walnaweb12a/b57/moo.greydragoncom/nodsw/sites/all/modules/views/handlers/views_handler_argument.inc on line 744.
  • strict warning: Declaration of views_handler_filter::options_validate() should be compatible with views_handler::options_validate($form, &$form_state) in /hermes/walnaweb12a/b57/moo.greydragoncom/nodsw/sites/all/modules/views/handlers/views_handler_filter.inc on line 607.
  • strict warning: Declaration of views_handler_filter::options_submit() should be compatible with views_handler::options_submit($form, &$form_state) in /hermes/walnaweb12a/b57/moo.greydragoncom/nodsw/sites/all/modules/views/handlers/views_handler_filter.inc on line 607.
  • strict warning: Declaration of views_handler_filter_boolean_operator::value_validate() should be compatible with views_handler_filter::value_validate($form, &$form_state) in /hermes/walnaweb12a/b57/moo.greydragoncom/nodsw/sites/all/modules/views/handlers/views_handler_filter_boolean_operator.inc on line 159.
Leeland's picture

A survey of various source code management layouts is located in the Software Professional Tidbits book at Repository Layouts.

== General Layout Guidelines ==

* Don't introduce the product into the source layout. Products will change, as will the names of modules, the repository core building blocks should remain constant.
* Support versioning on modules. As modules and products develop there will be a need to attach versions to the each release of a given module and product.
* Shared code is treated like any other sub-system or module. It is okay to keep shared code alongside non-shared code.
* Keep interfaces separate from implementation.
* Individual module/component internal layout is more flexible and should fit the logical structure of the module or needs of the developer.

== Questions To Consider ==

* Should interfaces be packaged as separate modules? (e.g. product interfaces, domain interfaces)
* How should extension points be packaged?
* Is configuration shared across all modules or is it tied to a module?
* Where should shared XML schema definitions be kept?
* Is there a way to enforce the allowed module dependencies with the layout?
* What layers make sense for the given product?
* Are there any platform agnostic resource definitions? (e.g. queues)

== NOD Source Layout ==

The NOD source code repositories are driven by three primary elements, each one creating a branch level.

=== Repository Structure ===

ssh+svn://svnserver/srv/svn/<branch_type>/nod/<product_line>/parent/<BRANCH>/pom.xml
ssh+svn://svnserver/srv/svn/<branch_type>/nod/<product_line>/base-<base_component>/<BRANCH>/...
ssh+svn://svnserver/srv/svn/<branch_type>/nod/<product_line>/subsystem-<subsystem>/<BRANCH>/...
ssh+svn://svnserver/srv/svn/<branch_type>/nod/<product_line>/product-<product>/<BRANCH>/...
ssh+svn://svnserver/srv/svn/<branch_type>/nod/<product_line>/suite-<suite>/<BRANCH>/...
ssh+svn://svnserver/srv/svn/<branch_type>/nod/<product_line>/tools/<BRANCH>/...

== Top Level: Driven by Release Strategy ==

At the top level, the desired control of releases (public or private) is reflected in the branching strategy, and thus the source code version control repository structure.

== Mid Level: Driven by Product Line Strategy ==

The second level reflects the desired granularity of releases (major/minor at subsystem granularity, patches at module granularity) is reflected in the branching strategy. This results in the following requirements:

* Each subsystem will live within its own "codeline"
* Each codeline must be self-contained; i.e. no source or build level sharing across codelines
* Sharing across codelines is achieved by leveraging maven repositories and published binaries

Example: A product line such as the wiki module for Drupal might be called "Naturally Wiki" which when released into beta, and then 1.0, 1.1, and 2.0 would have branches like:

ssh+svn://svnserver/srv/svn/pub-repo/nod/NaturallyWiki01beta/...
ssh+svn://svnserver/srv/svn/pub-repo/nod/NaturallyWiki01-0/...
ssh+svn://svnserver/srv/svn/pub-repo/nod/NaturallyWiki01-1/...
ssh+svn://svnserver/srv/svn/pub-repo/nod/NaturallyWiki02-0/...

== Third Level: Driven by Product Architecture ==

The next level is driven by generic architectural design for the product line. The various components are individually named according to design but assigned a prefix according to the following guidelines:

* base-<base module> is a pseudo-subsystem consisting of services used by multiple subsystems. It is considered very desirable to only put things into base as a last resort, and for clearly identifiable and obvious shared subsystem-wide services such as Logging and Configuration. It is very easy to get trapped into a bad situation of poor logic definition if this is used merely to avoid code duplication. Base modules may either follow the normal pattern for a subsystem module, or use the subsystem structure itself in the case of more elaborate base projects.
* product-<product> are considered to be a possibly-fluid grouping of subsystems into an interestingly shippable entity. They contain end to end tests specific to its grouping of subsystems as well as example projects for assembling deployable solutions.
# application-<module>/application creates a MIDU (e.g. skinny WAR, JAR, or Python egg) and CONTAINS ALL assets needed for the application, which are also provided in a separate application components/sub-modules (see next).
# application-<module>/components creates a specific component module (e.g. a JAR) containing the code specific to the application.
# application-<module>/dependency a grouping (e.g. a POM) of all of the application's "external" dependencies so they may be referenced in an assembly project to be included in the distribution assembly. Both the application project and the distribution project depend on the dependency project.
* subsystem-<subsystem> are considered to be complete services that by themselves do to provide a complete solution, but are intended to be wired together to create unique solutions. Examples of a subsystem would be an access control list service, or a user contribution accumulation points system.
* subsystem-<subsystem>/configuration contains the configuration definition and default values for the subsystem.
* subsystem-<subsystem>/resources contains the resources for the named subsystem.
* subsystem-<subsystem>/test contains named directories for specific integration testing systems such as FitNesse.
* subsystem-<subsystem>/test/itest is a pseudo-module consisting of cross module xUnit integration tests within a subsystem. Such integration tests may depend on the presence of environmental resources such as running databases. For that reason, as well as for build speed, such tests should only be run if a Maven profile is explicitly enabled.
* subsystem-<subsystem>/interfaces/extension-<module> contains the Extension Point Interfaces for the subsystem. It produces a MIDU (jar, perl module, etc.) per interface that is expected to be available in all tiers.
* subsystem-<subsystem>/interfaces/integration-<module> contains the Integration Point Interfaces for the subsystem. It produces a MIDU (jar, perl module, etc.) per interface that is expected to be available in all tiers.
* subsystem-<subsystem>/plugins contains any custom plugins which are specific to the functionality provided by the subsystem and intended for use outside the subsystem.
* suite-<suite> are considered to be a possibly-fluid grouping of products into an interestingly shippable entity. They contain end to end tests specific to its grouping of products as well as example projects for assembling deployable solutions.
* tools/plugins contains IDE/Maven projects for custom plugins that used for the build and assembly automation, these are not specific to product functionality and may not have dependencies on product artifacts.

Thread Slivers eBook at Amazon