Overview of Common Paths/Files in DocOps Lab Projects

This document is intended for AI agents operating within a DocOps Lab environment.

If you are creating a new DocOPs Lab project, use this guide to establish initial files. This also applies to adding major facilities or features to an existing project.

If you are just getting to know a DocOps Lab codebase, favor the project’s README.adoc file over this guide.

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.

Table of Contents

Documentation Paths
Configuration
Containerization
Ruby Files
Automation Paths
Quality Assurance Paths
Generative AI Paths

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.