--- ---

Development & Deployment Infrastructure

Local and cloud assets for DocOps Lab projects

This document addresses a standardized codebase structure and deployment configuration that is common across most DocOps Lab projects.

While nearly every project will differ from this in some ways, developers and writers should strive to maintain consistency and conform to these conventions wherever possible when contributing to DocOps Lab projects.

Common Project Paths

DocOps Lab projects tend to contain many of the same files across codebases. Documentation of these files in particular will be added when possible, but for now this basic guide will have to suffice.

Documentation Paths

Only two files are required in every DocOps Lab project, though most projects should contain most of these files, depending on the nature of the codebase. A docs/ or _docs/ directory is close to the third universal requirement, necessary by the time a project reaches version 1.0.0.

README.adoc

Project documentation in AsciiDoc format, providing an overview and instructions. DocOps Lab READMEs typically include single-sourcing data for the product as AsciiDoc attributes. See the Sourcerer project.

LICENSE

The project’s license file, specifying the terms under which the code can be used and distributed. Almost always MIT License.

docs/ / _docs/

Directory for additional documentation, guides, and related materials. Typically docs/ for product user documentation, whereas _docs/ is for (a) repos that are mainly for websites or (b) internal engineering documentation files (more often found at docs/_docs/). Both might be present in the case of a website that hosts docs and has its own docs.

A docs/ directory will typically have its own Gemfile, configs, and assets for Jekyll, Yard, and other generators. A _docs/ directory is usually a content-only subordinate to the main project and its content, and may not have separate configs or assets.

Configuration

.config/

Configuration files for tooling used in development, building, or QA/testing. Not always used.

.config/releasehx.yml

Configuration file for ReleaseHx, a tool for generating release notes and changelogs.

.config/jekyll.yml

Configuration file for Jekyll docs publication. For Jekyll extensions (themes and plugins), this file is typically ./_config.yml to conform to Jekyll defaults.

.config/vale.ini

Configuration file for Vale, a linter for prose, defining linting rules and styles.

.config/.vendor/

Directory for upstream configuration files, mostly or entirely managed by docopsab-dev gem. These files are not tracked in Git but are synced with upstream sources and maintained by DocOps Lab.

Containerization

Dockerfile

Dockerfile for building the project’s Docker image, defining the environment and dependencies.

.dockerignore

Specifies files and directories to ignore when building the Docker image.

docker-compose.yml

Defines and runs multi-container Docker applications, if applicable.

Ruby Files

These files are common to Ruby-based DocOps Lab projects. The Gemfile and Gemfile.lock may be present in non-Ruby codebases that use Ruby development dependencies, such as ReleaseHx.

Gemfile

Ruby Bundler file, specifying gem dependencies for the project.

Gemfile.lock

Generated by Bundler, this file locks the gem versions used in the project.

.ruby-version

Specifies the Ruby version used in the project.

<gemname>.gemspec

Ruby gem specification file, defining the gem’s metadata and dependencies.

Automation Paths

Rakefile

Ruby Rakefile for defining tasks and automation scripts.

scripts/

Custom scripts for automating tasks related to development, testing, and deployment.

.github/workflows/

GitHub Actions workflows for CI/CD, defining automated build, test, and deployment processes.

Quality Assurance Paths

Any files containing requirements, specifications, definitions, schemas, or tests should be stored in the specs/ directory, as detailed in DocOps Lab Testing & Specifications.

specs/

General directory for content that specifies, defines, or tests elements of the product. See DocOps Lab Testing & Specifications.

specs/data/

Definition and schema files.

specs/tests/rspec/

RSpec tests for Ruby codebases.

../<product-slug>-demo/

Major products typically have a sibling repo that serves as a proving grounds and/or for demonstrative purposes.

Generative AI Paths

.github/copilot-instructions.md

Instructions for GitHub Copilot, providing guidance on how any cloud-based GH Copilot assistance should be oriented toward a given codebase.

AGENTS.md

General for local coding agents. May duplicate .github/copilot-instructions.md or provide additional context.

.agent/

A directory for temporary/scratch files used by local coding agents.

Common Automation Scripts

Some DocOps Lab projects include highly customized automation scripts, but most contain or employ some common scripts that are primarily stored in this repository and/or deployed as Docker images for universal access during development, testing, and deployment.

These procedures can always be invoked by way of local scripts located in scripts/. These include:

  • build.sh

  • publish.sh

Common scripts are managed through the lnk:/docs/lab-dev-setup/[docopslab-dev gem].

Ruby projects will generally include a Rakefile (in the base directory), which automates various Ruby tasks.