Additions and deprecations
editAdditions and deprecations
editDocumentation is built for various branches, eg 0.90,
1.00, master. However, we release versions
0.90.0, 0.90.1, etc, which are all based on the
0.90 branch.
When adding new functionality to a branch, or deprecating
existing functionality, you can mark the change as
added, coming or deprecated. Use coming when the addition is
in an as yet unreleased version of the current branch, and added when
the functionality is already released.
The update_versions.pl script can be used to change coming notices
to added notices when doing a new release, and can also be used
to remove added, coming and deprecated notices completely.
Inline notifications
editUse inline notifications for small changes, such as the addition or deprecation of individual parameters.
[horizontal] `foo.bar`:: Does XYZ. added:[0.90.4] `foo.bar`:: Does XYZ. coming:[0.90.4] `foo.baz`:: Does XYZ. deprecated:[0.90.4]
|
|
Does XYZ. [0.90.4] Added in 0.90.4. |
|
|
Does XYZ. [0.90.4] Coming in 0.90.4. |
|
|
Does XYZ. [0.90.4] Deprecated in 0.90.4. |
You can also include details about additional notes in the notifications which show up when the user hovers over it:
[horizontal] `foo.bar`:: Does XYZ. added:[0.90.4,Replaces `foo.baz`] `foo.bar`:: Does XYZ. coming:[0.90.4,Replaces `foo.baz`] `foo.baz`:: Does XYZ. deprecated:[0.90.4,Replaced by `foo.bar`]
|
|
Does XYZ.
[0.90.4]
Added in 0.90.4. Replaces |
|
|
Does XYZ.
[0.90.4]
Coming in 0.90.4. Replaces |
|
|
Does XYZ.
[0.90.4]
Deprecated in 0.90.4. Replaced by |
If the details include a comma, you must use quotation marks. For example:
deprecated::[1.1.0,"Span started automatically by <<apm-start-span,apm.startSpan()>>"]
Section notifications
editUse section notifications to mark an entire chapter or section as added/deleted. Notifications can just refer to the version in which the change was made:
==== New section added::[0.90.4] Text about new functionality... ==== New section not yet released coming::[0.90.9] Text about new functionality... ==== Old section deprecated::[0.90.4] Text about old functionality...
With details…
editOr they can include extra text, including more Asciidoc markup:
[[new-section]] ==== New section added::[0.90.4,Replaces `foo.bar`. See <<old-section>>] Text about new functionality... [[coming-section]] ==== New section not yet released coming::[0.90.9,Replaces `foo.bar`. See <<old-section>>] Text about new functionality... [[old-section]] ==== Old section deprecated::[0.90.4,Replace by `foo.baz`. See <<new-section>>] Text about old functionality...
Old section
editDeprecated in 0.90.4.
Replace by foo.baz. See New section
Text about old functionality…