Skip to content

Latest commit

 

History

History
171 lines (121 loc) · 6.53 KB

README.adoc

File metadata and controls

171 lines (121 loc) · 6.53 KB
Raw

Personal Software Configuration Management

Welcome to Dotfiles!

The project Dotfiles is a personal project of mine. It serves me to manage the configuration files of my favorite software I use on a regular basis.

When you are an IT enthusiast like me then you know how much time and effort one is willing to spent in polishing his very own working environment to perfection. Therefore the Git repository of this project helps me to track the history of changes so that nothing is lost.

RFC Request for Comments 2119
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119.

For details please read the full RFC 2119 document.

Copyright & Licensing

GPLv3 GNU General Public License Version 3
Copyright (C) 2017  Tim Friske

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

For details please read the full GPLv3 license.

Project Organization & Management

Files & Folders

The top-level folder, i.e. the one this file resides in, MUST only contain the most important files, i.e. only those which give an introduction to or an overview about this project. But also files with long standing traditions and thus well-known meanings — files people simply expect to find — MAY be located here. Examples of these are text files such as README, INSTALL, CHANGELOG or NEWS, LICENSE or COPYING, CONTRIBUTING etc. with OPTIONAL file extensions such as adoc, md, txt etc.

The main content of this project — that is the configuration of each software — MUST be each contained in a separate folder named after the software. The folder name SHALL be written in lower case letters with words separated by single - hypen signs.

Further documentation pertaining to the project itself SHALL go into the top-level folder Documentation. Information specific to one software MUST be located underneath its own Documentation folder but SHOULD otherwise follow the same structure as the project documentation for consistency reasons.

The structure below each software configuration folder SHOULD be organized in a way that best fits the requirements of the individual software being configured. Nevertheless when commonalities, especially structural similarities, between certain software configurations evolve then these SHOULD be captured and endorsed for consistency where reasonable. This MAY mean to externalize common files and folders below the top-level folder Shared with OPTIONAL references, e.g. soft links, from the affected software configuration folders.

Text files and soft links MAY be versioned. Generated files, e.g. binary build artifacts, MUST NOT be put under version control. All other kinds of files not explicitly mentioned for OPTIONAL inclusion are REQUIRED to be excluded from version control.

Git Workflow

This project follows a simple Git workflow because it is mainly intended for personal use. Therefore the administrative overhead SHOULD be kept at a minimum. As such I picked the Integration-Manager workflow described in the book Pro Git rather than a more sophisticated Git workflow.

Here is an incomplete but quick overview about how the Integration-Manager workflow is practiced in this project — suggestions for improvements always welcome:

  • This Git repository

    • OPTIONAL

      • is cloned by a user who is interested in it.

      • is forked by a user who wants to contribute to it.

  • The branch `main'

    • REQUIRED

      • is the only source of truth.

      • is the only integration branch.

      • is the only branch where the latest more or less stable sources are to be found.

      • is consisting of mostly merge commits of signed tags pointing to completed topic branches except for a few self-contained but signed commits here and there.

      • is the authoritative history that can be easily followed with git-log --first-parent to get a summary of completed topics. Therefore updates MUST be fetched and rebased from upstream but MUST NOT be fetched and merged, e.g. with git-pull --rebase=false.

  • A topic branch

    • REQUIRED

      • is where all kinds of development happens. It is used for features, bugfixes, reworks, experiments etc.

      • is branched by the contributor from `main' when he starts working on the topic.

      • is completed by marking it with a signed tag.

      • is merged via a signed tag by the maintainer into `main' when he is convinced that the topic has matured enough to form a solid foundation for others to base their work upon.

    • OPTIONAL

      • is deleted shortly after its work was aborted or completed.

  • A signed tag

    • REQUIRED

      • pointing to a completed topic branch is not made public by pushing it to a public repository but by merging it into the main branch of that topic branch.

    • OPTIONAL

      • pointing to a completed topic branch is deleted shortly after it was merged into the main branch of that topic branch.

Bibliography

  • [rfc-2119] S. Bradner, RFC Request for Comments 2119, IETF Internet Engineering Task Force / Network Working Group, online version

  • [gpl-3.0] The GPLv3 authors, GPLv3 GNU General Public License Version 3, Free Software Foundation Incorporated, online version, offline version

  • [pro-git] Scott Chacon & Ben Straub, Pro Git 2nd Edition, APRESS, ISBN-13: 978-1-4842-0077-3, online version

  • [git-workflows] The Git authors, GITWORKFLOWS(7), Git project, online version