An Agnostic project file (agnostic.yaml) is a YAML file that describes the project with all its components, gives links to the documentation, repositories, contacts and so on. Ideally, to join a project, a developer should need no more than the project file, which replaces traditional "Getting started" e-mails or wiki pages.
The project file format is not strictly specified, so it may vary depending on the needs of a particular project. Common and recognizable by the command line tool parts are described below. Any project should respect these conventions.
A project file is a YAML (http://www.yaml.org/spec/1.2/spec.html) file. It contains at least one YAML document (for the project itself), and, optionally, more documents for components. Documents are separated by a line of three dashes (---).
The project document must present in the file once. It should be the first document in the file. It must have top-level mapping node project. Recognizable structure is as follows:
name-
(required) the project’s full name.
description-
human-readable description of the project.
bugs-
URL of the bug tracker.
docs-
a list of documentation sources. Each item is either a URL, or a human-readable text.
tools-
a list of tools to use. Each item is a mapping node, described below.
name-
(required) the tool’s name.
description-
human-readable description of the tool.
info-
URL to general resources about the tool, like the tool’s site.
download-
direct link to download the tool.
A component document describes a single component of the project. If the project is not split into components (e.g. it resides in a single repository and doesn’t depend on anything unusual), there should still be one component to describe the project’s sole source location.
A component document must have top-level mapping node component. Recognizable structure is as follows:
name-
(required) the component’s full name.
disabled-
If
true, this component is marked disabled and excluded from some batch operations. description-
human-readable description of the component.
alias-
the component’s short name.
githg-
the component’s source repository (Git or Mercurial, but not both) in a form suitable to run `git clone' or `hg clone'.
build-
shell script to build the component locally (developer build).
integrate-
shell script to perform integration build.
clean-
shell script to clean the component (undo previously done build).
buildAfter-
a list of names or aliases of other components from this file, which should be built before this component.
Dogfood project of Agnostic itself:
---
project:
name: Agnostic
description: Project definition tool (dogfood project).
bugs: https://github.com/dsavenko/agnostic/issues
docs:
- "https://github.com/dsavenko/agnostic/blob/master/README.md"
- "https://github.com/dsavenko/agnostic/tree/master/docs"
tools:
- name: asciidoc
description: doc generation tool.
info: http://www.methods.co.nz/asciidoc/index.html
- name: xmlto
description: shell-script tool for converting XML files to various formats.
info: https://fedorahosted.org/xmlto/
---
component:
name: libyaml
alias: yaml
description: "YAML parser"
hg: https://bitbucket.org/xi/libyaml
build: |
./bootstrap
./configure
make
sudo make install
---
component:
name: agnostic
alias: ag
description: "Main tool"
git: https://github.com/dsavenko/agnostic.git
build: |
make
buildAfter:
- libyamlMore samples are are in the samples/ directory of the Agnostic repository (https://github.com/dsavenko/agnostic/tree/master/samples). You may clone the repository, cd to samples/anything and run `ag clone' to see, how it works.