Skip to content

Latest commit

 

History

History
159 lines (118 loc) · 6.34 KB

main.adoc

File metadata and controls

159 lines (118 loc) · 6.34 KB

Unified Style Guide: Special Files 0.1

Table of Contents
Note
Text File Extensions

For text files, AsciiDoc is the officially recommended markup format. Either .adoc or .txt can be used for AsciiDoc file extensions.

1. Introduction

This document is provides guidelines for special file usage and structure. Following these guidelines should provide the following benefits:

  • Promote consistent special file usage.

  • Aid organization of information.

2. Archive Information Files

These files are used to provide information about the contents of an archive.

These files are always named either __arc_info__.<ext> (see extension info).

An archive is typically a zip file (although other similar formats may be used) that is simply used to store files.

Example __arc_info__.txt file for archive named archive_example.zip
= archive_example (1)
:date: 2 January 2000

This archive contains some example files.

  1. Title is the name of the archive file (without extension).

3. Changelog Files

Note
 The following is based off the Keep A Changelog guidelines with some modification.

These files are used to maintain the changes to a project or set of files.

These files are always named either changelog.<ext> or CHANGELOG.<ext> (see extension info).

Each release should be described in a dedicated section using the following naming convention: myproject-0.1.2 (2000-01-02)

Example changelog.txt for project named MyProject
= MyProject Changelog

== myproject-0.2.1 (2000-01-03)
=== Added
  - Added foo functionality.

== myproject-0.1.0 (2000-01-02)
=== Highlights
  - First release.

3.1. Common Sections

The following sections are common (omit those not applicable); the text of each subsection should be an unordered list:

  • Highlights - Quick summary of changes. Helps when there are many changes in a release.

  • Added - Describe new features.

  • Changed - Describe changes made to existing functionality.

  • Depreciated - Describe soon-to-be removed features.

  • Removed - Describe features that are now removed.

  • Fixed - Describe any bug fixes.

  • Security - Describe any vulnerabilities or security issues.

4. Directory Information Files

These text files are used to provide additional information on the use or purpose of a directory.

These files are always named __dir_info__.<ext> (see extension info) and are only applicable to the containing directory.

These files are formatted using AsciiDoc markup.

Example __dir_info__.txt file for directory named ExampleDirectory/
= ExampleDirectory (1)
:date: 2 January 2000

This directory contains files related to examples.

  1. Title is the name of the directory.

5. External Files

These files are used to indicate that the contents of a directory are sourced or directly copied for a different location.

These files are always named __ext_files__.<ext> (see extension info) and are only applicable to the parent directory.

6. Readme Files

These text files are used to provide reference information for a project.

These files are always named either readme.<ext> or README.<ext> (see extension info).

6.1. Common Sections

The following sections are common (omit those not applicable):

  • Introduction - Quick overview of the project.

  • Status - Current status of project regarding releases/versions, link to changelog.

  • Requirements - Required items for the project (building, running, etc).

  • Build - Procedure to build the project.

  • Installation - Procedure to install the project.

  • Usage - High-level explanation of project usage.

  • Design - Implementation details of the project.

  • Documentation - Additional project documentation.

  • License - Copy/license information.

  • Standards - List any standards (naming, versioning, etc) used by the project.

  • Issues - List of known issues/bugs.

  • Roadmap - Plan of upcoming changes/features.

  • Contacts - Information for contacting project maintainers.

  • Contributing - Information for contributing to the project.

  • Similar - Reference information about similar projects.

  • Q&A - Answers to questions not covered in other sections.

6.2. Status Section

The following boilerplate text is recommended for the project status:

  • The status of this project is planning. This project is not yet suitable for use.

  • The status of this project is pre-alpha. This project is not yet suitable for use other than testing.

  • The status of this project is alpha. This project is suitable for use but there may be instability as well as incompatibilities in new releases.

  • The status of this project is beta. This project is suitable for use but there may be incompatibilities in new releases.

  • The status of this project is production/stable. This project is suitable for use and new releases will maintain compatibility unless otherwise stated.

  • The status of this project is mature. This project is suitable for use and new releases will only address critical issues (e.g. bug fixes).

  • The status of this project is inactive. This project is suitable for use but no new releases are planned.

7. See Also Files

These files are used to provide locations of information relevant to the parent directory’s contents.

These files are always named __see_also__.<ext> (see extension info) and are only applicable to the parent directory.

Example __see_also__.txt file for directory named ExampleDirectory/
= SEE ALSO: ExampleDirectory (1)
:date: 2 January 2000

This directory contains files related to examples.

  1. Title is the name of the directory, the "SEE ALSO:" prefix is suggested.

8. User Scripts

These files are scripts intended for direct interaction with a user. Typically the user will begin the interaction by executing the script directly (rather than it being called by another script or utility).

These files are named using the following convention:

  • Leading underscore.

  • First word is a strong verb.

  • Remaining words describe script action.

  • Typically no longer than four words.

  • Capitalize the first letter of each word.

  • Separate words with an underscore.

  • Extension is based on the script type.

See the following naming examples:

  • _Cleanup.bat

  • _Build_HTML.py

  • _Start_Test_Server.sh