Init Job

Monteur has an Init Job to keep its setup in your repository seamlessly guided and simple. The aim is to make development easier and happier from the get go!

Init API is only available starting from Monteur version v0.0.2.

Initialize Your Repository

To initialize your repository, please:

Go to your repository's root directory.
Issue the following command:
1

monteur init

Monteur shall scan for its existence properly and if it is absent, Monteur will do the rest of the config files creation automatically.

Naming Your Project Metadata

Once done, the next thing to do is to fill up your project/app metadata. These information are crucial for documents generations, packaging metadata usage, and even release your product or publish your documents. You usually need to set them up once.

These configuration files were intentionally designed to be i18n compatible. For simplicity sake, this specification shall explain in en for English. There are a bunch of configurations to deal with so sit tight and let's go over each of them one-by-one.

App `metadata.toml`

This file is located in .configs/monteur/app/config/en/metadata.toml.

These are the main metadata used across various composer, writer, builder, packager, and publisher via Monteur's CI Jobs. The goal is to ensure all these outputs only source from 1 unified input (here) in order to maintain metadata consistency for your project/app.

Here are the list of information you need to update matching your project's metadata:

[Software]
Name = '<directory Name in title case>'
Command = '<directory name in filepath format>'
ID = '<directory name in filepath format>'
Version = 'v0.0.1' # version number
Category = 'devel' # software category
Suite = ''         # software suite (e.g. MSFT Office for MSFT Word)
Abstract = 'software XYZ tool in one single app.'
Description = """
Describe your software as much as you want. Please make sure you end it with
its unique selling pitch.
"""
Website = 'https://example.com/'

[Software.Contact]
Name = 'ACME Entity'
Email = [ '[email protected]' ]




[Software.Maintainers.ACME]
Name = 'ACME Entity'
Email = [ '[email protected]' ]
[Software.Maintainers.ACME.JointTime]
Year = '2021'




[Software.Contributors.ACME]
Name = 'ACME Entity'
Email = [ '[email protected]' ]
[Software.Contributors.ACME.JointTime]
Year = '2021'




[Software.Sponsors.ACME]
Name = 'ACME Entity'
Email = [ '[email protected]' ]
[Software.Sponsors.ACME.JointTime]
Year = '2021'

Software.Name
1. COMPULSORY - used as the documented product name.
2. Monteur automatically takes the directory name as project/app name. Please alter them accordingly.
3. Available since Monteur version v0.0.2.
Software.Command
1. COMPULSORY - used as the program name for invoking its command usage.
2. Whenever possible, try to keep it to 1 short sensible word only dash (-), alphanumeric characters, avoid space ( ), and avoid other symbols.
3. Available since Monteur version v0.0.2.
Software.ID
1. COMPULSORY - used as the stock keeping unit (SKU) identifier.
2. Monteur automatically takes the directory name as the project/app ID. Please alter them accordingly.
3. Whenever possible, try to keep it below 64 characters long using only dash (-), alphanumeric characters, avoid space ( ), and avoid other symbols.
4. Available since Monteur version v0.0.2.
Software.Version
1. COMPULSORY - indicate the current version of development.
2. Whenever possible, try to keep it as compliant to Semantic Versioning as possible.
3. This is the central control of the version number where it will be used for generating all necessary version files across the repository.
4. Available since Monteur version v0.0.2.
Software.Category
1. COMPULSORY - indicate the name of the catalog the project/app is belonged to.
2. Useful for packaging jobs like .deb.
3. Available since Monteur version v0.0.2.
Software.Suite
1. OPTIONAL - indicate the name of the software suite the project/app is belonged to.
2. For incompatible project/app, just leave the field blank ('').
3. Example: Microsoft Word in Microsoft Office (Suite).
4. Useful for packaging jobs like .deb.
5. Available since Monteur version v0.0.2.
Software.Abstract
1. COMPULSORY - a short, no article ("a", "an", "the") description with max 70 characters. Make it a pitch of your project/app.
2. Useful for packaging jobs like .deb.
3. Available since Monteur version v0.0.2.
Software.Description
1. COMPULSORY - a longer description joining after the abstract starting with a new paragraph.
2. Useful for packaging jobs like .deb.
3. Available since Monteur version v0.0.2.
Software.Website
1. OPTIONAL - the homepage of the project/app.
2. For incompatible project/app, just leave the field blank ('').
3. Useful for packaging jobs like .deb.
4. Available since Monteur version v0.0.2.
Software.Contact.Name
1. COMPULSORY - the contact entity's name (e.g. a person or company name) for project/app general inquiry purposes.
2. Useful for packaging jobs like .deb.
3. Available since Monteur version v0.0.2.
Software.Contact.Email
1. COMPULSORY - the contact entity's email addresses for project/app general inquiry purposes.
2. The first email address shall be given priority during a single email address selection.
3. Useful for packaging jobs like .deb.
4. Available since Monteur version v0.0.2.
Software.Maintainers.[ID]
1. COMPULSORY - a maintainer's identity. Details of the entity's fields are described in Software.[TYPE].[ID] section later.
2. This list is for the project/app maintainers, usually those who has power for maintaining the upkeep.
3. The [ID] can be anything and was meant for grouping the entity's information properly. To add more maintainers, simply duplicate the fields and provide another unique [ID] for it. In any cases, the [ID] MUST be the same if the same entity is also contributing other role like sponsors.
4. Use for assembling and rendering the project's/app's copyrights and citation list.
5. Available since Monteur version v0.0.2.
Software.Contributors.[ID]
1. COMPULSORY - a contributor's identity. Details of the entity's fields are described in Software.[TYPE].[ID] section later.
2. This list is for the project/app contributors, usually those who contribute once or twice in a blue moon into the project/app.
3. The [ID] can be anything and was meant for grouping the entity's information properly. To add more contributors, simply duplicate the fields and provide another unique [ID] for it. In any cases, the [ID] MUST be the same if the same entity is also contributing in another role like sponsors.
4. Use for assembling and rendering the project's/app's copyrights and citation list.
5. Available since Monteur version v0.0.2.
Software.Sponsors.[ID]
1. COMPULSORY - a financial sponsor's identity. Details of the entity's fields are described in Software.[TYPE].[ID] section later.
2. This list is for the project/app financial contributors, who contribute once/twice in a blue moon OR periodically into the project/app.
3. The [ID] can be anything and was meant for grouping the entity's information properly. To add more sponsors, simply duplicate the fields and provide another [ID] for it. In any cases, the [ID] MUST be the same if the same entity is also contributing in another role like maintainers.
4. Use for assembling and rendering the project's/app's copyrights and citation list.
5. Available since Monteur version v0.0.2.
Software.[TYPE].[ID].Name
1. COMPULSORY - name of a legal entity.
2. The [TYPE] refers to the Maintainers, Contributors, and Sponsors above.
3. Available since Monteur version v0.0.2.
Software.[TYPE].[ID].Email
1. COMPULSORY - list of emails of a legal entity.
2. The [TYPE] refers to the Maintainers, Contributors, and Sponsors above.
3. The first email is given the highest priority in a single email address selection.
4. Available since Monteur version v0.0.2.
Software.[TYPE].[ID].JointTime.Year
1. COMPULSORY - the year where an legal entity participated by giving into the project/app.
2. The [TYPE] refers to the Maintainers, Contributors, and Sponsors above.
3. Available since Monteur version v0.0.2.

App `help.toml`

This file is located in .configs/monteur/app/config/en/help.toml.

By default, Montuer created a default help guide data stored inside help.toml which contains all the known help file rendering templates. Some software distributors (e.g. .deb) requires the obselete help file made available in their packages. If you are not using it, please skip step.

Here are the list of information you need to update matching your project's metadata:

[Help]
Command = '$ {{ .App.Command }} help'
Description = '{{ .App.Abstract }}'
Resources = 'Visit {{ .App.Website }} for detailed documentations.'

[Help.Manpage]
Lv1 = """
.\\" {{ .App.Name }} - Lv1 Manpage
.\\" Contact {{ index .App.Contact.Email 0 }} for errors or typos.
.TH man 1 "{{- .App.Time.Day }} {{ .App.Time.Month }} {{ .App.Time.Year -}}" "{{- .App.Version -}}" "{{- .App.ID }} man page"

.SH NAME
{{ .App.Name }} - {{ .App.Abstract }}

.SH SYNOPSIS
{{ .App.Help.Command }}

.SH DESCRIPTION
{{ .App.Description -}}

.SH OPTIONS
{{ .App.Help.Description }}

.SH SEE ALSO
{{ .App.Help.Resources }}

#.SH AUTHORS
#{{ range $index, $owner := .App.Maintainers -}}
#       {{- $owner.Name }} ({{- index $owner.Email 0 -}})
#{{ end -}}
"""

Help.Command
1. COMPULSORY - the one-line command to call out its help display.
2. Use to guide users to call for help from the project/app (e.g. program --help or program help).
3. Available since Monteur version v0.0.2.
Help.Description
1. COMPULSORY - the description of the project/app.
2. By default, it is mapped to your Software.Abstract from the metadata.toml above.
3. Available since Monteur version v0.0.2.
Help.Resources
1. COMPULSORY - the instruction to obtain more details or for the project/app.
2. By default, it is mapped to visit Software.Website from the metadata.toml above.
3. Available since Monteur version v0.0.2.
Help.Manpage.[LEVEL]
1. COMPULSORY - the instruction to generate all corresponding [LEVEL] man pages for the project/app.
2. By default, Monteur generates level 1 (.1) man page that briefly describes the project/app and the help command (Help.Command above) to obtain actual help.
3. The [LEVEL] can be anything but generally advised to be numeric number starting from 1 and usually ends at 8. Please consult your operating system's specifications about each levels.
4. The [LEVEL]s are usually being used as the file extension depending on the CI Job recipe. Please consult the CI Job recipe for its modifications' compatibility.
5. Available since Monteur version v0.0.2.

App `[LICENSE].toml`

This file is located in .configs/monteur/app/copyrights/[LICENSE].toml. The [LICENSE] is a placeholder filename which can be anything useful for own referencing usage.

Montuer is designed to manage and generate multi-licenses project/app work environment. Hence you can include multiple licenses whenever applicable like dual-licensing or multiple licenses (e.g. media license + software license).

These license data files are the template and input data for rendering the publishable license file during a build or CI Job. It uses other metadata like the copyright holders to fill in the gap while still permitting project/app developer to overwrite them.

By default, Monteur generates Apache 2.0 Open Source License for maximum permissive and commercial friendly usage. This default file is meant for example referencing usage. Please remove it when it is incompatible to the project/app after creating your own license data file.

Here are the list of information you need for creating a [LICENSE].toml data file:

[Copyright]
Name = 'License Name' # license full name
ID = 'license-name'   # identifiable license ID
Comment = ''
Materials = [ '*' ]
Holders = [
        # A string with year, then name, then email with diamond braces. Ex.:
        #
        #   '2021 John S. Smith <[email protected]>',
        #
        # If the list is empty, all maintainers, contributors, and sponsors
        # shall be attached to it.
]
Notice = """
License notice usually prepend in front of source codes.
"""
Text = """
Full license text body.
"""

Copyright.Name
1. COMPULSORY - name of the license for human comprehension.
2. Available since Monteur version v0.0.2.
Copyright.ID
1. COMPULSORY - ID of the license for tracking and identifcation use.
2. For open source licenses, please consult SPDX Licenses List for maximum compatibility identifier.
3. Available since Monteur version v0.0.2.
Copyright.Comment
1. OPTIONAL - comment for the license to appear in the rendering.
2. Please leave it empty ( "") if it is no comment.
3. Available since Monteur version v0.0.2.
Copyright.Materials
1. COMPULSORY - list out all the files or the naming patterns of the materials where the license is applicable.
2. General symbols is allowed like * stands for any or all pattern of. Example: *.jpg refers to all files with .jpg file extension, regardless of its location in the repository, is subjected this this license.
3. To apply the license to ALL files, simple just retain the '*' which stands for all files regardless name or extensions.
4. Available since Monteur version v0.0.2.
Copyright.Holders
1. OPTIONAL - list out all the copyright holders of this license, overriding the default rendering completely.
2. The format MUST be:
  1 2
  
  Format : '[YEAR] [FULL NAME] <[EMAIL]>', Example: '2021 John S. Smith <[email protected]>',
  NOTE: The tailing comma (,) is removed for the last entry.
3. If left empty, all maintainers, contributors, and sponsors from metadata.toml above shall be assembled and formatted automatically to fill in the gap.
4. Available since Monteur version v0.0.2.
Copyright.Notice
1. COMPULSORY - a short copyright notice usually preprended in front of a source codes, emit into command-line request, or an IP document.
2. Available since Monteur version v0.0.2.
Copyright.Text
1. COMPULSORY - full license body in plaintext without the copyright holders prepend to it.
2. Available since Monteur version v0.0.2.

App `debian.toml`

This file is located in .configs/monteur/app/config/en/debian.toml.

These are .deb package specific information meant for Debian-based Linux operating system. The fields and data here are meant for offical dehelper packager to systematically work out a signed .deb package file. Depending on which packaging software you're using (e.g. debuild), certain information are COMPULSORY. Monteur itself is using this packager complying to the Debian Policy itself to ensure maximum compatiblity with the ecosystem.

If you're not deploying a .deb package distribution, please skip this configuration file.

Here are the list of information you need to update matching your project's metadata:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66


[DEB]
Compat = 11
Rules = """
#!/usr/bin/make -f

# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1

%:
	dh $@

override_dh_auto_build:
	echo "nothing to override"
override_dh_slibdeps:
	echo "nothing to depend on"
"""

[DEB.Control]
Essential = false
PackageType = 'deb'
Priority = 'optional'
RulesRequiresRoot = 'binary-targets'
Standards = '4.6.0'
Section = 'devel'

[DEB.Relationships]
'Build-Depends' = [
	'debhelper (>= 11)',
]
'Depends' = [
]

# More Info:
#  https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-vcs-fields
[DEB.VCS]
Type = 'Vcs-Git'
URL = 'https://example.com/git'
Branch = 'main'
#Path = '.'

[DEB.Testsuite]
Paths = [
	# 'relative/path/to/debTestScript',
]

[DEB.Copyright]
Format = 'https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/'
Disclaimer = ''
Comment = ''

[DEB.Changelog]
Urgency = 'low'

[DEB.Source]
Format = '3.0 (native)'
LocalOptions = """
"""
Options = """
"""
LintianOverrides = """
# supply the license file in case OS did not supply one

# we are go package so it is okay not to specify Depends:
"""

[DEB.Install]

DEB.Compat
1. COMPULSORY - generates the DEBIAN/compat file.
2. The values must be compliant to debhelper Compatibility Level .
3. Only used if you are using debhelper to build the .deb package.
4. Available since Monteur version v0.0.2.
DEB.Rules
1. COMPULSORY - generates the DEBIAN/rules file.
2. The values must be compliant to Debian Rules Policy .
3. Available since Monteur version v0.0.2.
DEB.Control
1. COMPULSORY - generates the DEBIAN/control file.
2. The generated file is compliant to Control Fields Policy .
3. Available since Monteur version v0.0.2.
DEB.Control.Essential
1. COMPULSORY - set the .deb not to be uninstalled if marked as essential packages.
2. Accepts only true or false as complying to Essential Policy .
3. Available since Monteur version v0.0.2.
DEB.Control.PackageType
1. COMPULSORY - set the .deb not to be uninstalled.
2. Accepts only deb or udeb complying to Package Type Policy .
3. Available since Monteur version v0.0.2.
DEB.Control.Priority
1. COMPULSORY - set the .deb package's installation priority nature.
2. Only accepts value from Package Installation Priority .
3. Available since Monteur version v0.0.2.
DEB.Control.RulesRequiresRoot
1. COMPULSORY - set the .deb package to be handled by the level of root permissions.
2. Accepts only values from Rules Requires Root Policy .
3. Available since Monteur version v0.0.2.
DEB.Control.Standards
1. COMPULSORY - set the package validator standards.
2. Accepts only the semantic versioning ID as value from Debian Policy Checklist.
3. Available since Monteur version v0.0.2.
DEB.Control.Section
1. COMPULSORY - set the package catagory.
2. Accepts only the standards ID from Debian Archive Subsection.
3. Available since Monteur version v0.0.2.
DEB.Relationships.[TYPE]
1. COMPULSORY - generates all the project/app relationship with other packages inside the DEBIAN/control file.
2. The [TYPE] MUST be the exact name of the relationship type stated in Debian Package Relationship like Build-Depends, Build-Depends-Indep, Build-Depends-Arch, and etc.
3. The value MUST be a list of corresponding .deb packages.
4. Available since Monteur version v0.0.2.
DEB.VCS
1. COMPULSORY - generates the VCS field inside DEBIAN/control file.
2. More info: Debian Archive Subsection .
3. Available since Monteur version v0.0.2.
DEB.VCS.Type
1. COMPULSORY - specify the version control type used to manage the repository.
2. Accepts only the value from: Debian Control VCS Fields .
3. Available since Monteur version v0.0.2.
DEB.VCS.URL
1. COMPULSORY - specify the URL source to obtain a copy of the project/app code repository.
2. Accepts only the value from: Debian Control VCS Fields .
3. Available since Monteur version v0.0.2.
DEB.VCS.Branch
1. COMPULSORY - specify the version control branch responsible for this packaging from the repository.
2. Accepts only the value from: Debian Control VCS Fields .
3. Available since Monteur version v0.0.2.
DEB.VCS.Path
1. OPTIONAL - specify the directory pathing of the version control repository.
2. Accepts only the value from: Debian Control VCS Fields .
3. Leave the field absent or commented if unused.
4. Available since Monteur version v0.0.2.
DEB.VCS.Testsuite.Paths
1. OPTIONAL - list out the test suite files for testing the .deb package.
2. Leave the list empty if unused.
3. Accepts only the value from: Debian Control Testsuite Fields .
4. Available since Monteur version v0.0.2.
DEB.Copyright
1. COMPULSORY - generates the DEBIAN/copyright file.
2. The actual copyright entries are generated internally using app copyright.toml data above. These are additional data requirements specific to .deb packaging.
3. Available since Monteur version v0.0.2.
DEB.Copyright.Format
1. COMPULSORY - states the copyright format version.
2. Accepts only the format version in full URL from: Debian Copyright Format .
3. Available since Monteur version v0.0.2.
DEB.Copyright.Disclaimer
1. COMPULSORY - states your copyright disclaimers.
2. Accepts only the value complying to the selected standards format from: Debian Copyright Format .
3. Available since Monteur version v0.0.2.
DEB.Copyright.Comment
1. COMPULSORY - states your copyright comments.
2. Accepts only the value complying to the selected standards format from: Debian Copyright Format .
3. Available since Monteur version v0.0.2.
DEB.Changelog
1. COMPULSORY - generate the necessary data for DEBIAN/changelog file.
2. The actual changelog entries are generated via Prepare CI Job recipe. These fields act as supplimentary where the data is not suitable to be placed in the recipe file itself.
3. Available since Monteur version v0.0.2.
DEB.Changelog.Urgency
1. COMPULSORY - states the current changelog entry's urgency.
2. Only accepts values from Changelog Urgency .
3. Available since Monteur version v0.0.2.
DEB.Source
1. COMPULSORY - generates all files in DEBIAN/source directory.
2. Available since Monteur version v0.0.2.
DEB.Source.Format
1. COMPULSORY - defines the .deb package format by generating DEBIAN/source/format file.
2. Only accepts values from Source Format .
3. When in doubt, use 3.0 (native) instead.
4. Available since Monteur version v0.0.2.
DEB.Source.LocalOptions
1. COMPULSORY - generates DEBIAN/source/local-options file.
2. Only accepts values from Source Local Options .
3. Available since Monteur version v0.0.2.
DEB.Source.Options
1. COMPULSORY - generates DEBIAN/source/local-options file.
2. Only accepts values from Source Options .
3. Available since Monteur version v0.0.2.
DEB.Source.LintianOverrides
1. COMPULSORY - generates DEBIAN/source/lintian-overrides file.
2. Only accepts values from Source Lintian Overrides .
3. Available since Monteur version v0.0.2.
DEB.Install
1. COMPULSORY - generates DEBIAN/install file.
2. The values are a set of key = value data, where the:
  - Key - designate the installation path where it should be relative without the starting root ( /) path.
  - Value - designate the pathing to the installation target.
3. Example:
  1 2
  
  [DEB.Install] 'usr/bin' = 'monteur'
  will install a packaged monteur executable file into usr/bin directory of an operating system.
4. Available since Monteur version v0.0.2.

Assemble Monteur's CI Jobs

Now that the repository with Monteur ready, it's time to assemble the CI Jobs compatible to your project/app. Montuer is designed to make different jobs portable yet maintainable across its ecosystem so don't you worry.

For starter, please head over to the CI Jobs' Galleries and shop for existing continuously improved recipes. That will save you tons of times and get to work.

Alternatively, you can develop your on CI Job recipe. Each recipe has its own configurations so please go through them accordingly.

Epilogue

That's all for initializing Monteur into your project/app repository. If you have any question, please feel free to raise your question at our Issues Section.

Init Job

Initialize Your Repository

Naming Your Project Metadata

App metadata.toml

App help.toml

App [LICENSE].toml