Tag: structure

TOC

• Preface
• Directory Levels
  • <FunctionalDir>/
  • <FunctionalDir>/trunk/
  • <FunctionalDir>/<BranchName>/
  • <CategoryDir>/
  • <WebSiteDirName>/
  • <CodeDirName>/
• Repository or Site Types
  • Version Directory
  • Release Repository
  • InternalWebSite
  • InternalWikiSite
  • README Files
• Directory Examples
  • Version Repository
  • Release Repository
  • Internal Web Site
  • Internal Wiki Site

---

Preface

This document is to be used as a guideline for organizing and naming document folders and directory trees, which are shared by many people. This is a structure that I have evolved over 15 years while working at 6 different companies. I figure it would be on major version “8.0”, if it were a product. In the last two companies, I haven’t had to make any major structural changes. Of course, only about 10% of the top levels get used, but they are there if the categories start to get “too deep.”

A number of goals are embedded in this structure:

• Avoid the 90-degree collision of mixed structures. For example, a structure could start with “projects”, then sub-folders are used for “functional” areas, marketing, engineering, etc. While another structure starts with functional areas, then the project is repeated across each of the areas. Either structure could work, but using both will lead to confusion. The “project” structure is what most people start with, but it has a major flaw. Often documents in the project need to be shared with external partners, but functional groups will want to keep some documents private to their group. So the project files start to be copied to alternate structures, because opening up the top project directory, to external partners, reveals too much information. In other words, I’ve noticed that the sensitivity of information tends to be grouped stronger by functional boundaries, than by projects. Marketing will partner with an external group, but engineering wants to keep its code private. Engineering may outsource the work, and marketing will want the business plans kept secret. This is a problem because the whole point of a repository is to share information. So the top directories for this template are by functional areas, not project.

• Avoid using different names for the same thing. For example, if you have configuration files, these can be collected in a directory named: etc, or config, but don’t use both names. Pick one and be consistent within the functional area or “category”. This document lists some recommended names for different categories. Before making up a name, look around the other project areas and notice the naming patterns used by other projects. Don’t assume that the oldest or even the newest names are the preferred names–other engineers could have just not cared enough to make things consistent with other code. If you abbreviate a name, then always use the abbreviation.

• Clean-code refactoring tip: if you see an inconsistent naming pattern (either not self-consistent or not company style consistent), then fix it! Your IDE should make it easy to change names across multiple files. If not, learn to use find, grep, sed, perl, etc. A professional engineer should be able to make global changes across thousands of files with confidence in their tools.

• The top-level directories are “fixed”, and sibling directories, at the same level, categorize the same content. This makes it easy to write scripts for archiving and publishing. It also makes it easier to create and include paths in software code, because they are more “regular”. It is also easy to add new libraries, with little or no changes to the build scripts.

• The structure of similar content is grouped together.

• The “branch level” for software can be placed at almost any fixed level. But keep that level consistent. Do not branch at other levels. (Note: this part is not relevant for “git” repositories.) Notice the branches are on the same level as trunk. Creating a “branches/” dir. level is unnecessary, because there should not be that many “active” branches. Inactive branches are deleted to keep the upper levels clean. Of course, the deleted branches are still available in the repository. With subversion and other modern version management tools, there also isn’t much need for a “tags/” directory. If you want to keep track of the source that goes with particular versions, an easier way is to just create a “Version” file that holds the version tag name and the repository path (branch) and id for that version. Using this style of branching and tagging, will keep the workspaces “clean” and focused on “active” code, while still having the flexibility to quickly get any desired branch and version. The best branch points are: just under each functional area or just under each category area. When branching, it is not necessary to include all of the content. Only the content that will be changed or saved, needs to be “copied” to the branch. The branch level is mainly determined by what parts a company normally includes in each release and on the dependencies of the parts. Of course, the branch level is not needed for the non-versioned areas, like a wiki tool, or a shared directory.

---

Directory Levels

This is the most important part. Each level has a “meaning.”

Continue reading General Release Directory Structures