1Releases
2========
3
4Functional Changes
5------------------
6
7If the documenation wants to point out,
8that a feature has been added
9or some functionality changed in a specific version,
10use the following role:
11
12If you want to point out a limitation in the Bareos functionality, the following formatting should be used::
13
14   :sinceVersion:`<version>: <Summary>`
15
16version
17   Bareos version number, e.g. ''18.2.5''.
18
19Summary
20   A short summary.
21
22This role will only display ''Version >= <version>''. The <Summary> will appear only in the index.
23
24The index will contain entries:
25
26* bareos-<version>
27
28  * Summary
29
30and
31
32* Summary
33
34  * bareos-<version>
35
36Example:
37
38.. literalinclude:: /DocumentationStyleGuide/example/sinceVersion-documentation-sphinx.rst.inc
39   :language: none
40
41This will be displayed as:
42
43.. include:: /DocumentationStyleGuide/example/sinceVersion-documentation-sphinx.rst.inc
44
45
46Note
47~~~~
48
49``:sinceVersion:`` is a legacy role. Sphinx itself offers
50
51  * https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded
52  * https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionchanged
53  * https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated
54
55Until defined otherwise, you should use ``:sinceVersion:`` instead of these.
56
57
58Release Notes
59-------------
60
61If you want to display the release notes of a Bareos stable release, use the following template:
62
63.. \newcommand{\releasenote}[2]{
64    \subsection*{bareos-#1}
65    \addcontentsline{toc}{subsection}{\protect\numberline{}#1}%
66    \label{bareos-#1}
67    \index[general]{bareos-#1!Release Notes}%
68    #2
69   }
70
71.. literalinclude:: /DocumentationStyleGuide/example/releasenotes-template.rst.inc
72
73Example:
74
75.. literalinclude:: /DocumentationStyleGuide/example/releasenotes-17.2.7.rst.inc
76
77
78See the output at :ref:`bareos-17.2.7`\ .
79
80.. COMMENT include:: /DocumentationStyleGuide/example/releasenotes.rst.inc
81
82
83
84Reference to a Release
85----------------------
86
87To refer to a release, use::
88
89    :ref:`bareos-<VERSION>`
90
91Example:
92
93  This refers to :ref:`bareos-17.2.7`\ .
94
95Output:
96
97This refers to :ref:`bareos-17.2.7`\ .
98
99
100.. Release Notes - Unstable Version
101   --------------------------------
102
103   TODO: required?
104
105  If you want to display the release notes of a bareos unstable release, the following formatting should be used:
106
107.. \newcommand{\releasenoteUnstable}[2]{
108    \subsection*{\textit{bareos-#1 (unstable)}}
109    %\addcontentsline{toc}{subsection}{\protect\numberline{}#1}%
110    %\index[general]{bareos-#1!Release Notes}%
111    #2
112   }
113
114
115
116URLs
117----
118
119Release URL - Bareos.org
120~~~~~~~~~~~~~~~~~~~~~~~~
121
122If you want to display the release download URL from the Bareos.org site, the following formatting should be used:
123
124.. \newcommand{\releaseUrlDownloadBareosOrg}[1]{%
125   \url{http://download.bareos.org/bareos/release/#1/}%
126   }
127
128   Post Conversion Changes
129   ${PERL} 's#\\releaseUrlDownloadBareosOrg\{(.*?)\}#//http://download.bareos.org/bareos/release/\1/#g' ${DESTFILE}
130
131http://download.bareos.org/bareos/release/18.2/
132
133
134Release URL - Bareos.com
135~~~~~~~~~~~~~~~~~~~~~~~~
136
137If you want to display the release download URL from the Bareos.com site, the following formatting should be used:
138
139.. \newcommand{\releaseUrlDownloadBareosOrg}[1]{%
140   \url{http://download.bareos.org/bareos/release/#1/}%
141   }
142
143   Post Conversion Changes
144   ${PERL} 's#\\releaseUrlDownloadBareosCom\{(.*?)\}#//https://download.bareos.com/bareos/release/\1/#g' ${DESTFILE}
145
146
147https://download.bareos.com/bareos/release/18.2/
148
149
150Contributions Download URL
151~~~~~~~~~~~~~~~~~~~~~~~~~~
152
153If you want to display the download URL of plugins available on Bareos.org, the following formatting should be used:
154
155.. \newcommand{\contribDownloadBareosOrg}{%
156   \url{http://download.bareos.org/bareos/contrib/}%
157   }
158
159   Post Conversion Changes
160   ${PERL} 's#\\contribDownloadBareosOrg\{(.*?)\}#//http://download.bareos.org/bareos/contrib/#g' ${DESTFILE}
161
162http://download.bareos.org/bareos/contrib/
163