/multi-topic-level-repo-template

Git repository template for multiple titles with both downstream and one or more upstream distros

Primary LanguageShell

multi-topic-level version 1.0 Template Git Repository

This is a fully-customizable Git repository that can be quickly and easily cloned to begin new documentation projects, or migrate old documentation projects into the repository structure that Content Services is converging on as part of its FY17 goals.

This repository structure has the following properties:

  • It is verified to work with the Tooling team’s Docs2Drupal and Docs 2.0 publication systems.

  • It is based on the "library," or "multi-title" repo model, meaning that one or more titles are located in a single Git repository. This repository structure can work with any number of titles, from one to whatever.

  • The repository structure serves to make it clear which content—usually toics—is/are shared between different distributions ("distros") of a title, shared between more that one title, or potentially local to a single distro of a title.

  • The need to use file-naming conventions to signify levels of sharing (a.k.a. "Hungarian notation") is reduced due to the directory structure making it more explicit.

  • It can be mirrored between Github and Gitlab by the Tooling team.

  • Content from other repositories can be pulled into this one using the Git subtree (or Git submodels if absolutely necessary).

  • This repository structure has been structured so that it works with discrete chunks of content included from the topics and topics/shared subdirectories of each title. That is, it is based on, and will work best with, a topic-oriented content development model.

In addition, this repository structure has been designed to work with the following content development models:

  • All content development is performed in the Github repository, for any number of titles and distros, provided that release versions are more-or-less in sync between those distros. The Github repository is mirrored to Gitlab solely in order to publish using the Docs2Drupal/Docs 2.0 toolchain (i.e. Pantheon).

  • Upstream content development (by engineering, community members, etc.), for any number of titles and distros, happens in Github. Downstream development (by CCS, engineering), for any number of titles and distros, happens in Gitlab.

  • All content development for any number of titles and distros happens in Gitlab.

  • This repository structure is extremely flexible and should be able to account for any other development models. Contact Silas if you have any questions about whether this repository structure can work for your project.

Repository Structure Overview

├── README.adoc
├── docs
│   ├── my-title-a
│   │   ├── enterprise
│   │   │   ├── master-docinfo.xml
│   │   │   ├── master.adoc
│   │   │   └── topics -> ../topics
│   │   ├── topics
│   │   │   ├── shared -> ../../shared
│   │   │   ├── topic-1.adoc
│   │   │   ├── topic-2.adoc
│   │   │   ├── topic-4.adoc
│   │   │   └── topic-5.adoc
│   │   └── upstream-1
│   │       ├── master-docinfo.xml
│   │       ├── master.adoc
│   │       └── topics -> ../topics
│   ├── my-title-b
│   │   ├── enterprise
│   │   │   ├── master-docinfo.xml
│   │   │   ├── master.adoc
│   │   │   └── topics -> ../topics
│   │   ├── topics
│   │   │   ├── shared -> ../../shared
│   │   │   ├── topic-1.adoc
│   │   │   ├── topic-2.adoc
│   │   │   ├── topic-4.adoc
│   │   │   └── topic-5.adoc
│   │   └── upstream-1
│   │       ├── master-docinfo.xml
│   │       ├── master.adoc
│   │       └── topics -> ../topics
│   └── shared
│       ├── attributes.adoc
│       ├── images
│       ├── templates
│       │   └── revision-info.adoc
│       ├── topic-shared-1.adoc
│       └── topic-shared-2.adoc
└── resources
    ├── asciidoc-writing-guide.adoc
    └── scripts
        └── buildGuides.sh

How to Use This Repository Template

  1. Clone this repository:

    $ git clone https://github.com/silasrh/multi-topic-level-repo-template.git

  2. Delete the .git configuration and data directory:

    $ cd multi-topic-level-repo-template
$ rm .git -fr

  3. Modify the global attributes in docs/shared/attributes.adoc for your project.

  4. Make modifications to the first title:

  5. Copy the entire docs/my-title-a directory and its contents to docs/<your_actual_first_title_name>.

  6. Rename the enterprise and upstream-1 directories to match the names of your distros.

  7. Define the my-title-a and product-build attributes in master.adoc. Ensure the first title builds after the modifications and then repeat these steps for each additional title.

  8. If you are migrating existing content to this repository template, it is highly recommended to put all content into the topics directories for the appropriate titles, even if the content is not shared between distros. (There are more reasons for putting content that isn’t shared between distros of a title or multiple titles into the <title>/topics directory, at least at first, but they are beyond the scope of this README. For a discussion of the reasoning, which touches on content development workflow, contact Silas.)

multi-topic-level Revision History

1.0

  • rename My_Title_A, My_Title_B and Upstream_1 directories to my-title-a, my-title-b and upstream-1 naming patterns to make navigating the Git repo as fast as possible. Thank you, jross, for making the suggestion!

  • docs/shared/templates/document-attributes.adoc moved to docs/shared/attributes.adoc.

  • all includes of document-attributes.adoc changed to correct for new attributes.adoc location.

  • scripts/buildGuides.sh moved to resources/scripts/buildGuides.sh.

  • latest version of the EAP team’s asciidoc-writing-guide.adoc added to the resources directory for referential convenience.

  • RepoTemplateVersion and RepoTemplateCodeName attributes defined in docs/shared/attributes.adoc.

  • remove topic-6 and topic-7 because they are unnecessary for illustrative purposes.

Pre-1.0

  • contains typo in repository structure diagram: "images — This folder contains all imagess"

  • buildGuides.sh (98 lines, 86 sloc) does not work correctly because it had not been updated from the script developed by EAP