1. Introduction

This guide is meant to assist contributors to the AMQ 7 documentation.

1.1. Dependencies

  • asciidoctor

  • ccutil

  • make

  • python

1.2. Project layout

BOOK_DIR/                          # The source for a book
common/                              # Shared include files
common/attributes.adoc               # Global book attributes
images/                              # Shared image files
scripts/                             # Build scripts
upstreams/                           # Copies of upstream docs

1.3. Book layout

BOOK_DIR/master.adoc               # The main asciidoc entry point
BOOK_DIR/master-docinfo.xml        # Book metadata
BOOK_DIR/common/                   # Symlink to ../commmon/
BOOK_DIR/images/                   # Symlink to ../images/
BOOK_DIR/CHAPTER.adoc            # Book-local chapter files
BOOK_DIR/CHAPTER-SECTION.adoc  # Book-local section files

2. Setting up git

AMQ 7 uses git to manage repositories. This guide explains how to set up your system to connect to the proper git repositories.

2.1. Documentation repositories

AMQ 7 documentation uses the following documentation repositories:

amq7-documentation-contrib (GitHub)

A private GitHub repo that hosts all of the AMQ 7 documentation. All downstream contributions to the documentation are made in this repo.

amq7-docs (GitLab)

A GitLab repo for pushing doc updates to Pantheon for publication on the Red Hat Customer Portal. This repo essentially functions as a "mirror" of amq7-documentation-contrib; no doc updates should be made in it.

2.2. Installing git

If using RHEL or Fedora, open your terminal and enter the proper installation command.

RHEL

$ sudo yum install git
Tip
 To get sudo access for RHEL 7, go to Applications > Red Hat Internal > Switch the …​, and then select the I need sudo access checkbox.
Tip
 To bypass the need for sudo access go to Applications > System Tools > Software, and in the Search box, type Git and press Enter. Select the check box for "Fast Version Control System git-1.8.3.1-6.el7_2.1 (64-bit)" and press Enter to install.

Fedora

$ yum install git (up to Fedora 21)
$ dnf install git (Fedora 22 and later)

Other operating systems

2.3. Configuring git

Once you have git installed you’ll want to set up your git account.

Procedure

  1. Open Terminal

  2. Set your name and email

    $ git config --global user.name "YOUR_NAME"
$ git config --global user.email "YOUR_EMAIL"
    Tip
    		 The email you specify should be the same one found in your email settings. To keep your email address hidden, see Keeping your email address private.

  3. Set your git defaults

    $ git config --global pull.rebase true
$ git config --global push.default simple

2.4. Forking the upstream (GitHub) repository

Fork the amq7-documentation-contrib upstream repository to create a copy under your own GitHub ID. This allows you to work on multiple features and push changes to branches in your own GitHub instance so that you do not have to worry about losing work. When you are ready, you can request the changes to be merged back into the upstream repository.

Procedure

  1. Open a browser and navigate to the upstream repository located at https://github.com/rh-messaging/amq7-documentation-contrib

  2. Click Fork located in the upper right under your profile icon.

  3. Select your user account for the location of the forked repository. This creates your own copy of the repository under your own GitHub ID.

2.5. Adding your SSH keys to GitHub

If you choose to use the SSH address for your clones, you will need to add an SSH Key to GitHub first.

Procedure

  1. Open Terminal.

  2. Check to see if you have a public SSH key:

    $ ls ~/.ssh/

  3. If you don’t have a key, generate one:

    $ ssh-keygen -t rsa -C "YOUR_EMAIL"

  4. Open your key in an editor:

    $ cd ~/.ssh/
$ vi id_rsa.pub

  5. Copy the contents of the file to your clipboard.

  6. Visit https://github.com/settings/keys

  7. Click New SSH Key.

  8. Give your key a name and paste the contents of your key file.

  9. Click Add SSH Key.

2.6. Cloning your forked upstream repository

Clone your forked repository to bring your GitHub repository files to your local machine. Your forked repository is now the origin repository for your local files.

Note
 For more information about forking and cloning, consult the official Gitlab documentation.

Using SSH

Procedure

  1. Open Terminal.

  2. Navigate to the directory where you want to create the new repository folder.

  3. Type the following command:

    $ git clone git@github.com:USERNAME/amq7-documentation-contrib.git

  4. Navigate to the newly created amq7-documentation-contrib folder.

    $ cd amq7-documentation-contrib/

Using HTTPS

While there are fewer steps in this option, you have to enter your GitHub credentials with every change you make.

Procedure

  1. Open Terminal.

  2. Navigate to the directory where you want to create the new repository folder.

  3. Type the following command:

    $ git clone https://github.com/USERNAME/amq7-documentation-contrib.git

  4. Enter your GitHub credentials to complete the clone.

  5. Navigate to the newly created amq7-documentation-contrib folder.

    $ cd amq7-documentation-contrib/

2.7. Adding the upstream as a remote repository

Once you have your fork checked out and cloned locally, add the downstream repository as a remote.

Using SSH

Procedure

  1. List the current remote repositories:

    $ git remote -v
origin	git@github.com:USERNAME/amq7-documentation-contrib.git (fetch)
origin	git@github.com:USERNAME/amq7-documentation-contrib.git (push)

  2. Add the upstream as a remote repository and fetch its contents. This allows you to check out and work with the latest source code.

    $ git remote add -f upstream  git@github.com:rh-messaging/amq7-documentation-contrib.git

  3. Enter your GitHub credentials to complete the remote add process.

  4. Verify the new remote was added:

    $ git remote -v
origin	git@github.com:USERNAME/amq7-documentation-contrib.git (fetch)
origin	git@github.com:USERNAME/amq7-documentation-contrib.git (push)
upstream	git@github.com:rh-messaging/amq7-documentation-contrib.git (fetch)
upstream	git@github.com:rh-messaging/amq7-documentation-contrib.git (push)

Using HTTPS

Procedure

  1. List the current remote repositories:

    $ git remote -v
origin	https://github.com/USERNAME/amq7-documentation-contrib.git (fetch)
origin	https://github.com/USERNAME/amq7-documentation-contrib.git (push)

  2. Add the upstream as a remote repository and fetch its contents. This allows you to check out and work with the latest source code.

    $ git remote add -f upstream  https://github.com/rh-messaging/amq7-documentation-contrib.git

  3. Enter your GitHub credentials to complete the remote add process.

  4. Verify the new remote was added:

    $ git remote -v
origin	https://github.com/USERNAME/amq7-documentation-contrib.git (fetch)
origin	https://github.com/USERNAME/amq7-documentation-contrib.git (push)
upstream	https://github.com/rh-messaging/amq7-documentation-contrib.git (fetch)
upstream	https://github.com/rh-messaging/amq7-documentation-contrib.git (push)

2.8. Updating repository URLs

If the upstream repository is moved, you can change the downstream URL by using the following command:

$ git remote set-url upstream https://github.com/rh-messaging/amq7-documentation-contrib.git

Use the following command any time you need to fetch the latest source code locally:

$ git fetch upstream

2.9. References

3. Contributing to the documentation

The following guide walks you through contributing to the AMQ 7 documentation.

3.1. Getting started

Before you begin you need to:

  1. Install and set up Git

  2. Install and set up ccutil

3.1.1. Refreshing upstream content

If you plan on contributing to content in the upstream you want to be sure to have a fresh copy of that content before beginning.

We use special make targets to fetch and update in-tree copies of upstream content. After using these targets, be sure to commit the changes.

The syntax used is make refresh-upstream-UPSTREAM_NAME

For example:

$ make refresh-upstream-qpid-dispatch
$ make refresh-upstream-qpid-jms
$ make refresh-upstream-qpid-proton

3.2. Contributing to the documentation

Once you have your local repository set up and have up to date copies of upstream content you need to follow these steps to contribute to the documentation.

Procedure

  1. Open your terminal

  2. cd to the directory where your documentation resides

  3. Checkout the contrib branch

    $ git checkout contrib

  4. Update your local repository and fork with the upstream content

    $ git pull upstream contrib
$ git push origin contrib --force

  5. Create a new branch for your work (using the JIRA number is helpful)

    $ git checkout -b BRANCH_NAME

  6. Make your edits in the editor of your choice

  7. Save your changes locally

  8. If you are creating new files, add the files to the repository

    $ git status
$ git add FILE_NAME
    Note
    		 It is best to not use git add *. Adding everything can accidentally add files you do not intend to. It is better to use the command reflected here.

  9. Build your changes by using ccutil or make-based tooling to confirm your edits are correct

    1. If adding an entirely new section or making complex edits, be sure to share your build on your Red Hat fileshare so that you can provide a link to those reviewing your content

      $ cd GUIDE_NAME
$ ./buildGuide.sh

  10. Commit your changes

    $ git commit -a -m "MESSAGE"

  11. Verify that your commit only includes the files you edited.

    [amqdoc2870 f144b8d] AMQDOC 2870: Add note about not committing all
 1 file changed, 2 insertions(+)

    1. If the number of files edited in your commit is more than than you worked on, you might have added files you did not intend to.

  12. If you have been working on your edits for a while, it is possible that content in the repository has changed. It is good practice to fetch any new content before your push your changes to your fork.

    $ git fetch --all
$ git rebase origin/contrib

  13. Push your changes to your fork

    $ git push origin HEAD

  14. If the update is rejected because the commit is behind, merge your changes

    $ git pull upstream contrib
$ git push -f origin HEAD

  15. Visit your fork on GitHub

  16. Click Compare & pull request

  17. If a SME review is needed:

    1. Add SME Review Needed label.

    2. When SME review is complete, remove SME Review Completed label and go to step 16.

  18. Add Peer Review Needed label and assign a Reviewer.

    1. When peer review has been completed, the reviewer deletes the Peer Review Needed label and adds the Peer Review Done label.

  19. When Peer Review Done label has been added:

    1. If no changes are needed, remove Peer Review Done label and add Ready for Merge label.

    2. If changes are needed and the changes are minor, make changes to the files, commit, and push, and then remove Peer Review Done label and add Ready for Merge label.

    3. If you want an additional review on the updated content, add the Peer Review Needed label and ask for another review in a comment.

3.3. Merging commits

Commits are merged weekly on Friday by the "Mergemaster" following the instructions in the Documentation Administration Guide.

4. Configuring your environment to build the documentation

When you make changes to the documentation, it is a good practice to perform a local test build to verify the book builds successfully and renders as you expect before you submit the merge request back to upstream master. This section describes how to configure your environment to build the documentation.

You can build the books by using either make-based tooling or Red Hat’s ccutil, however, be aware that only ccutil catches build errors such as invalid xrefs and missing includes.

For that reason, you must install ccutil to test the build before you merge your changes.

Note
 The ccutil utility requires Ruby. If you have not installed Ruby, you can use this command to install it: yum -y install ruby

4.1. Installing ccutil

Procedure

  1. Configure the engineering and ccs-tools repositories by creating two files:

    1. In a text editor, create a repo file with the following lines (where VERSION is the major release version number of RHEL installed on your personal computer, for example, 7):

      [eng-rhel-VERSION]
name=ENG Internal - $releasever
baseurl=http://download.devel.redhat.com/rel-eng/repos/eng-rhel-VERSION/$basearch/
enabled=1
gpgcheck=0
skip_if_unavailable=1
priority=1

    2. Save the file as /etc/yum.repos.d/eng-rhel-VERSION.repo

    3. In a text editor, create another repo file with the following lines:

      [ccs-tools]
name=CCS Tools for RHEL $releasever
baseurl=http://ccs-tools.usersys.redhat.com/yum/$releasever/$basearch/
enabled=1
gpgcheck=0
skip_if_unavailable=1
priority=1

    4. Save the file as /etc/yum.repos.d/ccs-tools.repo

      Tip
      		 If you do not have root access, you can not move the files to the correct location by using the File Manager. Instead save the file to your home folder and use Terminal to copy the files to the correct location: 
      sudo cp ~/ccs-tools.repo /etc/yum.repos.d/
sudo cp ~/eng-rhel-VERSION.repo /etc/yum.repos.d/

      Remember to replace VERSION where indicated with the correct version number.

  2. Verify that you are connected to the internal network and run the following command to install the ccutil utility:

    $ sudo yum install ccutil

  3. Check that ccutil is installed correctly by running the following command:

    $ ccutil --help

    If ccutil was successfully installed, then you should see the help printed like the example below. Example output:

    Usage: ccutil [OPTIONS] COMMAND [ARGS]...

Options:
  -c, --config CONFIG  Specify a config file to use.
  --debug              Print debugging information.
  --verbose            Print detailed information about each step.
  -v, --version        Print the version of the application.
  -h, --help           Show this message and exit.

Commands:
  clean    Clean any build data left on the local machine.
  compile  Builds the book locally.
  history  Show the history for a book/article.
  list     Lists the books/articles currently available.
  logout   Logout and close any current authenticated sessions.
  video    Transcode, upload or list videos.
  whoami   Prints details about authenticated sessions.

4.2. Using ccutil

Ccutil can be used to build a local copy of the documentation for review.

Procedure

  1. Navigate to the guide folder.

  2. In Terminal, type ./buildGuide.sh

  3. The output can be found in build/tmp/en-US/html-single/index.html or you can click the link presented in Terminal

    Finished html-single
broker (AsciiDoctor) is located at:  file:///home/USER/amq7docs/amq7-documentation-contrib/docs/broker/html/broker.html
broker (ccutil) is located at:  file:///home/USER/amq7docs/amq7-documentation-contrib/docs/broker/build/tmp/en-US/html-single/index.html

To share your results with others, publish your results to your personal Red Hat file share. Learn more about setting up your personal file share.

5. Using Make With AMQ 7 documentation

When you make changes to the documentation, it is a good practice to do a local test build to verify the book builds successfully and renders as you expect before you submit the merge request back to upstream master.

Make is a useful tool for building your documentation and pushing it to your public Red Hat file share so that peer and quality reviewers can see your edits as the customer would.

You can also build your documentation with ccutil. Be aware that only ccutil catches build errors such as invalid xrefs and missing includes.

5.1. Make commands to build documentation

$ cd PROJECT_DIR

$ make help
[default]      Equivalent to 'make preview'
preview        Generate asciidoctor output (faster)
build          Generate ccutil and asciidoctor output (slower)
test           Run all build scripts and output checks
clean          Removes build/ and other build artifacts
publish        Copy output to http://file.rdu.redhat.com/~USERNAME/amq-docs/

$ make preview
[...]

See the output in your browser at file: PROJECT-DIR/build/welcome/index.html

The entry point for the resulting output is build/welcome/index.html in your checkout.

To publish your results to your personal file share, use make publish. It copies the local output to a Red Hat file server. Learn more about setting up your personal file share.

5.2. Make commands to refresh upstream repositories

We use special make targets to fetch and update in-tree copies of upstream content. After using these targets, be sure to commit the changes.

The syntax used is make refresh-upstream-UPSTREAM_NAME

For example:

$ make refresh-upstream-qpid-dispatch
$ make refresh-upstream-qpid-jms
$ make refresh-upstream-qpid-proton

6. AsciiDoc format reference

Tips for which AsciiDoc markup to use when formatting text.

Monospace (`)
Item Example

File names and paths

The `/home/user/.bashrc` file …​

Literal values

If the value is `true` …​

Configuration attributes

Set the `enabled` attribute …​

Java class names

The `java.sql.Connection` class …​

Java annotations

The `@Clustered` annotation …​
Italics (_)
Item Example

Guide titles

See the _Installation Guide_ …​

Emphasis for a term (only emphasize first time)

_High availability_ refers to the …​
Bold (*)
Item Example

GUI items (menus, buttons)

Click the *Add* button and …​
Underline (value)
Item Example

Default item in a multi-select

`yes|[.underline]#no#|maybe`

7. Style guidelines

7.1. Style guides to reference

When writing content we use the following style guides in order:

  1. IBM Style Guide (printed)

  2. IBM DeveloperWorks Editorial Style Guide

  3. Red Hat Brand Standards

  4. AMQ 7 Terms and Conventions

  5. Red Hat Glossary of Terms and Conventions

  6. Red Hat Corporate Style Guide

  7. AMQ 7 Documentation Information Architecture Guidelines

  8. AMQ 7 Screenshot Guidelines

  9. This document (which does include some of the most commonly used rules from the previous guides)

7.2. Style guidelines

7.2.1. General styles

Table 1. General quick reference
Item Use Not

File system names and paths, symbols, and literals.

`filename`

GUI items (Match the capitalization of the button)

*bold*

Navigation link text

*bold*

Superuser console commands

$ sudo

#

Emphasis

_yay_

*yay*

List of options (underline the default if there is one)

1|[.underline]#2#|3

1/2/3

Decimal integers < 10

four

4

Decimal integers >= 10

12

twelve

Hexadecimal integers (always numeric, lowercase x)

0x123

0X13

Number ranges (always use numerals)

1-20

1-twenty

Do not use Latin abbreviations

that is

i.e.

and so on

etc.

for example

e.g.

Cannot

cannot

can not

And

and

&

Choices

and

and/or

or

Heartbeating

heartbeating

heart-beating
Additional general guidelines

  • Stick to one file per chapter unless the content is too long, excluding reusable topics.

  • Don’t use contractions, ;).

  • Document IDs are book-scoped, so they don’t need the book title in them.

  • End bulleted and numbered lists with periods unless the items listed are simple names.

  • The words "server" and "broker" are not capitalized unless they begin a sentence or appear in a title.

  • Avoid the word "simply" unless it clarifies.

  • For substitution of {attr} in code blocks, use [subs=+attributes].

  • For styling of *bold* (bold) in code blocks, use [subs=+quotes].

  • Do not use the word 'the' before 'Broker'. It is just 'Broker'

  • When referring the reader to more information, use: "For more information about TOPIC, see RESOURCE."

7.2.2. Naming files

Table 2. File Names Quick Reference
Item Use Not

Custom attributes

`ThisStyle`

`this-style`

`this_style`

File and directory names

`module_this-style`

`module-this_style`

`ModuleThisStyle`

Learn more about naming files in the Files and Attributes appendix.

7.2.3. Styling headings and titles

AMQ 7 uses sentence-case headings for modules, tables, and figures.

Table 3. Headings Quick Reference
Item Use Not

Section headings

Configuring the system with RHEL

Configuring the System with RHEL

Configuring The System With RHEL

Procedure Titles (gerund)

Configuring

Configure

Table and block titles

This is an example

This is an Example

This Is An Example

Hyphenated headings

Configuring point-to-point messaging

Configuring Point-To-Point Messaging

Configuring Point-to-point Messaging

Unnumbered titled sections

[discrete]

7.2.4. Section IDs

The format defined here is recommended because it is the most stable and versatile of anchor formats, and supports variables that enable topics to be reused and cross-referenced properly. Other anchor formats include [[anchor-name]] and [#anchor-name], but these formats either do not support variables for content reuse or do not support certain character types, such as periods. These limitations cause errors at build time.

Learn more about reusing content in the Modular Documentation Reference Guide.

Table 4. IDs quick reference
Item Use Not

Document IDs

[id="same-as-section-heading-{context}"]

[[this-heading-here]]

[[ThisHeadingHere]]

[#anchor-name]

7.2.5. Styling replaceables

Replaceable values in the text and code should be styles using monospace, lowercase, arrow brackets, and hyphens.

Table 5. Replaceables quick reference
Item Use

Replaceable value

`<some-value>`

Location of broker instance

`<broker-instance-dir>`

Component install directory

`<install-dir>`
Tip
 If using a replaceable within a source block, you will need to add subs="+quotes"` to the source tag for it to render. (For example : [source,options="nowrap",subs="+quotes"]).
Table 6. Links quick reference
Item Use Not

Zip files

zip

.zip

ZIP

Tar files

tar

.tar

TAR

External links

link:github.com[GitHub^]

link:github.com[GitHub]

Internal links

xref:doc_id[Section Title]

xref:doc_id[Section Title^]
Note
 If you use the caret syntax more than once in a single paragraph, you may need to escape the first occurrence with a backslash.
Important
 Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. When they are enabled, you must surround the link text in double quotes if it contains a comma.
Additional link guidelines

  • Refer to the top-level sections of books as chapters, not sections or topics.

  • Do not split link paths across lines when wrapping text. This will cause issues with the doc builds.

7.2.7. Styling punctuation

General punctuation guidelines

  • Do not refer to an individual punctuation mark or special character by its symbol alone.

  • Use the name alone, or use the name followed by the symbol in parentheses.

  • Use the name alone if the punctuation mark or special character is standard, such as a comma or period, and including the symbol would clutter the text.

  • Include the symbol in parentheses when a punctuation mark or special character is not well known or when including the symbol improves clarity.

Table 7. Punctuation quick reference
Character Name

&

Ampersand

< >

Angle brackets, opening angle bracket, or closing angle bracket

" "

Double quotation marks, opening quotation marks, or closing quotation marks (not quotes or quote marks)

' '

Single quotation marks, opening quotation mark,or closing quotation mark (not quotes or quote marks)

%

Percent sign

( )

Parentheses, opening parenthesis, or closing parenthesis

$

Dollar sign

*

Asterisk (not star)

#

Number sign

!

Exclamation point (not exclamation mark or bang)

7.3. See also

8. Terms and conventions

The following list of Terms and Conventions are specific to AMQ 7. In addition to this guide, see the Red Hat Glossary of Terms and Conventions for the usage conventions for the more commonly used documentation terms.

Responsible person: Ben Hardesty (bhardest@redhat.com)

acceptor (noun)

Description: An acceptor defines the way a client can connect to a broker instance.

Use it: yes

Incorrect forms:

See also:

AMQ Broker (noun)

Description: A component of Red Hat AMQ, it is a full-featured, message-oriented middleware broker. It offers specialized queueing behaviors, message persistence, and manageability.

Use it: yes

Incorrect forms: A-MQ Broker, The AMQ Broker, Red Hat Broker, JBoss Broker

See also: broker distribution, broker instance

AMQ Clients (noun)

Description: A suite of messaging libraries supporting multiple languages and platforms. It enables users to write messaging applications that send and receive messages. AMQ Clients is a component of Red Hat AMQ.

Use it: yes

Incorrect forms: A-MQ Clients, Red Hat Clients, JBoss Clients

See also: client application, messaging API

AMQ Console (noun)

Description: A management tool for administering AMQ brokers and routers in a single graphical interface.

Use it: yes

Incorrect forms: A-MQ Console, Red Hat Console, JBoss Console

See also:

AMQ Core Protocol JMS (noun)

Description: An implementation of JMS using the ActiveMQ Artemis Core protocol. This is sometimes called Core JMS.

Use it: yes

Incorrect forms:

See also: JMS, Core protocol

AMQ Interconnect (noun)

Description: A component of Red Hat AMQ, it is a messaging router that provides flexible routing of messages between any AMQP-enabled endpoints, whether they are clients, servers, brokers, or any other entity that can send or receive standard AMQP messages.

Use it: yes

Incorrect forms: Interconnect, Router, A-MQ Interconnect, Red Hat Interconnect, JBoss Interconnect

See also: router

AMQP (noun)

Description: Advanced Message Queuing Protocol. It is an open standard for passing business messages between applications or organizations (https://www.amqp.org/about/what). AMQ Broker supports AMQP, and AMQ Interconnect uses AMQP to route messages and links.

Use it: yes

Incorrect forms:

See also:

Artemis (noun)

Description: The upstream project for AMQ Broker (Apache ActiveMQ Artemis). When referring to AMQ Broker, always use the Red Hat product name.

Use it: with caution

Incorrect forms:

See also: AMQ Broker

Use it: yes

Incorrect forms: auto-link, AutoLink

See also:

broker distribution (noun)

Description: The platform-independent AMQ Broker archive containing the product binaries and libraries.

Use it: yes

Incorrect forms:

See also: AMQ Broker, broker instance

broker instance (noun)

Description: A configurable instance of AMQ Broker. Each broker instance is a separate directory containing its own runtime and configuration data. Use this term to refer to the instance, not the product.

Use it: yes

Incorrect forms:

See also: AMQ Broker, broker distribution

broker cluster (noun)

Description: A group of brokers to be grouped together in order to share message processing load. In A-MQ 6, this was called a network of brokers.

Use it: yes

Incorrect forms:

See also:

brokered messaging (noun)

Description: Any messaging configuration that uses a message broker to deliver messages to destinations. Brokered messaging can include brokers only, or a combination of brokers and routers.

Use it: yes

Incorrect forms:

See also:

client application (noun)

Description: An application or server that connects to broker instances, routers, or both to send or receive messages. This should not be confused with AMQ Clients, which is the messaging library used to create the client application.

Use it: yes

Incorrect forms:

See also: producer, consumer, AMQ Clients, messaging API

connection (noun)

Description: A channel for communication between two peers on a network. For AMQ, connections can be made between containers (clients, brokers, and routers). These are sometimes also called network connections.

Use it: yes

Incorrect forms:

See also: acceptor, listener, connector, amq-container, session

connection factory (noun)

Description: An object used by a JMS client to create a connection to a broker.

Use it: yes

Incorrect forms:

See also:

connector (noun)

Description: A configurable entity for AMQ brokers and routers. They define an outgoing connection from either a router to another endpoint, or from a broker to another endpoint.

Use it: yes

Incorrect forms:

See also: connection

consumer (noun)

Description: A client that receives messages.

Use it: yes

Incorrect forms:

See also: client application

container (noun)

Description: A top-level application, such as a broker or client. Connections are established between containers.

Use it: yes

Incorrect forms:

See also: connection

Core API (noun)

Description: An API for the ActiveMQ Artemis Core protocol. It is not supported by AMQ Broker.

Use it: yes

Incorrect forms:

See also: Core protocol, AMQ Core Protocol JMS

Core protocol (noun)

Description: The native messaging protocol for ActiveMQ Artemis.

Use it: yes

Incorrect forms:

See also: AMQ Core Protocol JMS

delivery (noun)

Description: The process by which a message is sent to a receiver. Delivery includes the message content and metadata, and the protocol exchange required to transfer that content. When the delivery is completed, it is settled.

Use it: yes

Incorrect forms:

See also: message settlement

destination (noun)

Description: In JMS, this is a named location for messages, such as a queue or a topic. Clients use destinations to specify the queue or topic from which to send or receive messages. Only use this term in the context of JMS. In all other instances, use address.

Use it: with caution

Incorrect forms:

See also: message address

direct routed messaging (noun)

Description: A messaging configuration that uses routers only to deliver messages to destinations. This can also be called routed messaging.

Use it: yes

Incorrect forms:

See also:

Dispatch Router (noun)

Description: The upstream component for AMQ Interconnect (Apache Qpid Dispatch Router). When referring to AMQ Interconnect, always use the Red Hat product name.

Use it: with caution

Incorrect forms:

See also: AMQ Interconnect

JMS (noun)

Description: The Java Message Service API for sending messages between clients.

Use it: yes

Incorrect forms:

See also:

Use it: yes

Incorrect forms:

See also:

Use it: yes

Incorrect forms:

See also: message routing

listener (noun)

Description: A configurable entity for AMQ routers and messaging APIs. A listener defines a context for accepting multiple, incoming connections on a particular TCP address and port.

Use it: yes

Incorrect forms:

See also: connection

live-only (noun)

Description: A broker high availability policy for scaling down brokers. If the broker is shut down, its messages and transaction state are copied to another live broker.

Use it: yes

Incorrect forms: live only

See also:

master-slave group (noun)

Description: A broker high availability configuration in which a master broker is linked to slave brokers. If a failover event occurs, the slave broker(s) take over the master broker’s workload.

Use it: yes

Incorrect forms: live-backup group

See also:

master broker (noun)

Description: The broker that serves client requests in a master-slave group.

Use it: yes

Incorrect forms: live broker

See also: master-slave group, slave broker

message (noun)

Description: A mutable holder of application content.

Use it: yes

Incorrect forms:

See also:

message address (noun)

Description: The name of a source or destination endpoint for messages within the messaging network. Message addresses can designate entities such as queues and topics. The term address is also acceptable, but should not be confused with TCP/IP addresses. In JMS, the term destination may be used.

Use it: with caution

Incorrect forms:

See also: destination

message routing (noun)

Description: A routing mechansim in AMQ Interconnect. A message route is the message distribution pattern to be used for a message address. With message routing, a router makes a routing decision on a per-message basis when a message arrives.

Use it: yes

Incorrect forms:

See also: link routing

message settlement (noun)

Description: The process for confirming that a message delivery has been completed, and propagating that confirmation to the appropriate endpoints. The term settlement is also acceptable.

Use it: yes

Incorrect forms:

See also: delivery

messaging API (noun)

Description: The client libraries and APIs used to create client applications. These libraries are provided by AMQ Clients.

Use it: yes

Incorrect forms:

See also: AMQ Clients, client application

MQTT (noun)

Description: MQ Telemetry Transport protocol. It is a lightweight, client-to-server, publish/subscribe messaging protocol (http://mqtt.org/). AMQ Broker supports MQTT.

Use it: yes

Incorrect forms:

See also:

OpenWire (noun)

Description: A cross-language wire protocol that enables JMS clients to communicate with AMQ Broker (http://activemq.apache.org/openwire.html).

Use it: yes

Incorrect forms:

See also:

peer-to-peer messaging (noun)

Description: A messaging operation in which a client sends messages directly to another client without using a broker or router. This term should only be used to refer to client-to-client communication, not direct routed messaging.

Use it: yes

Incorrect forms:

See also: direct routed messaging

producer (noun)

Description: A client that sends messages.

Use it: yes

Incorrect forms:

See also: client application

qdmanage (noun)

Description: A generic AMQP management client used for managing AMQ Interconnect.

Use it: yes

Incorrect forms: Qdmanage, QDMANAGE

See also:

qdstat (noun)

Description: A management client used for monitoring the status of a AMQ Interconnect router network.

Use it: yes

Incorrect forms: Qdstat, QDSTAT

See also:

queue (noun)

Description: A stored sequence of messages. In AMQ, queues are hosted on brokers.

Use it: yes

Incorrect forms:

See also:

receiver (noun)

Description: A channel for receiving messages from a source.

Use it: yes

Incorrect forms:

See also: consumer, source, sender

Red Hat AMQ (noun)

Description: A lightweight messaging platform that delivers information and easily integrates applications. It consists of several components (message broker, interconnect router, and clients) that support a variety of configurations. Always use the full product name (Red Hat AMQ) or short product name (AMQ).

Use it: yes

Incorrect forms: A-MQ, Red Hat A-MQ

router (noun)

Description: A configurable instance of AMQ Interconnect. Routers are application layer programs that route AMQP messages between message producers and consumers. Routers are typically deployed in networks of multiple routers with redundant paths. When using this term, be careful not to confuse it with network device routers.

Use it: yes

Incorrect forms:

See also: AMQ Interconnect

routing mechanism (noun)

Description: The type of routing to be used for an address. Routing mechanisms include message routing and link routing.

Use it: yes

Incorrect forms:

See also:

routing pattern (noun)

Description: The path messages sent to a particular address can take across the network. Messages can be distributed in balanced, closest, and multicast routing patterns.

Use it: yes

Incorrect forms:

See also:

sender (noun)

Description: A channel for sending messages to a target.

Use it: yes

Incorrect forms:

See also: producer, target, receiver

session (noun)

Description: A serialized context for producing and consuming messages. Sessions are established between AMQ peers over connections. Sending and receiving links are established over sessions. Use this term with caution, as users typically do not need to understand it to use AMQ.

Use it: with caution

Incorrect forms:

See also: connection

sharded queue (noun)

Description: A distributed queue in which a single logical queue is hosted on multiple brokers. Routers are typically used with sharded queues to enable clients to access the entire sharded queue instead of only a single shard of the queue.

Use it: yes

Incorrect forms:

See also: queue

slave broker (noun)

Description: In a master-slave group, this is the broker (or brokers) that takes over for the master broker to which it is linked.

Use it: yes

Incorrect forms: passive broker

See also: master-slave group, master broker

source (noun)

Description: A message’s named point of origin.

Use it: yes

Incorrect forms:

See also: target

SSL/TLS (noun)

Description: The Secure Socket Layer protocol (SSL) and its successor, the Transport Layer Security protocol (TLS). As both of these protocols are frequently called "SSL", always use "SSl/TLS" to avoid confusion.

Use it: yes

Incorrect forms: SSL, TLS, TLS/SSL

See also:

STOMP (noun)

Description: Simple (or Streaming) Text Oriented Message Protocol. It is a text-oriented wire protocol that enables STOMP clients to communicate with STOMP brokers. AMQ Broker can accept connections from STOMP clients.

Use it: yes

Incorrect forms:

See also:

target (noun)

Description: A message’s destination. This is usually a queue or topic.

Use it: yes

Incorrect forms:

See also: source

topic (noun)

Description: A stored sequence of messages for read-only distribution.

Use it: yes

Incorrect forms:

See also:

9. Information architecture guidelines

At Red Hat, we write modular documentation that is based on user-stories. This means that each assembly documents a user story. Learn more in the Modular Documentation Reference Guide.

10. Screenshot guidelines

10.1. Summary

  • Images should be saved as PNG or JPG, with a width of at least 660 px, at 110 dpi. Try to keep file size less than 300 KB.

  • Screenshots supplement the text, not replace it. Do not rely on images to provide information or context.

  • Do not include any testing/pre-release labels.

  • Do not include any personally identifying information.

  • Capture just the part of the screen or window that users must focus on; do not include window headers in the final screenshots unless completely necessary.

  • Manipulate your screenshots to condense important information in them and limit empty GUI space and other inconsequential parts.

  • Give the image file the same name as the anchor used in it (which is the same as or similar to the module heading) separated by dashes. Add the image prefix a with an underscore to the file. For example, image_guided-decision-example.adoc for a screenshot or image in the guided decision module.

10.2. General guidelines

  • Screen captures can be useful and successful when they achieve one or more of these objectives:

    • Illustrate a user interface that is fairly complex or difficult to explain in text

    • Help the user find a small element in a complex user interface

    • Show the results of a series of steps or user actions

    • Orient readers who are reading the publication without the user interface in front of them

  • Use the smallest number of screenshots possible.

  • Use screenshots to provide verification for the reader, rather than instruction. For example, screenshots are meant to supplement the text, not replace it. Do not rely on images to provide information or context. Instead, use them only to provide the reader with orientation.

    Note
    		 Example 1: Do not tell the reader to fill out a form according to the image; instead list the values needed for the form in text.
    Note
    		 Example 2: Do not include an image of the directory tree; instead tell the user exactly where to find the file in running text (…​/standalone/configuration/standalone.xml).

  • Bearing in mind the affect on localization and accessibility, aim to write your document so that, were you to remove all screenshots from the book, the text still makes sense.

    Note
    		 For example: Do not write "see image below" or "as is shown in the image"

  • When you are snapping a GUI form, fill it with relevant input first.

  • Verify that the screenshots do not include any testing/pre-release labels.

  • Verifty that the screenshots do not include any personally identifying information.

    Note
    		 For example: Always use 'test' as the username or fake contact information. If including the browser title bar hide your bookmarks and use a default browser theme.
    Tip
    		 Use Chrome Dev Tools to select elements on the page and rewrite their contents.

  • Include the cursor, mouse pointer, or menus only when their presence is significant.

  • Increase font size in the browser if it is hard to read before snapping the image.

  • Capture just the part of the screen or window that users must focus on.

    Note
    		 For example: Unless necessary, do not include window headers in the final screenshots to indicate your currently used window manager or desktop environment.

  • If possible, try not to cut any elements on the screen.

  • Show the user interface elements exactly as they are displayed for most users for quick recognition.

    Note
    		 For example: If you have a custom theme on your system, disable it and take the screenshot using the default theme.

  • Do not add borders around or drop shadows to your screenshots.

  • Do not use rounded corners. If the screenshot contains rounded corners, then that is acceptable. But, the screenshot should remain squared.

10.3. Tech specs

  • Image width should be at least 660 px (internal tools will automatically resize the image to a max width of 660 px).

  • The preferred format is PNG or JPG .

  • The output resolution of images should be 110 dpi to ensure good quality in the generated PDF.

    Tip
    		 In GIMP, select Image/Scale Image…​ to set resolution

  • If possible, try to keep screenshot size less than 300 KB.

  • If possible, avoid snapping images in various terminals with 8-bit color scale or less.

  • Manipulate your screenshots to condense important information in them and limit empty GUI space and other inconsequential parts.

    Note
    		 You can do this by setting a low screen resolution or resizing your browser window to a smaller size. Remember that you should only do this if it does not adversely affect the readability of the image.
    Note
    		 If you need to take a screenshot of the entire window, use a tool such as the Window Resizer Google Chrome extension to ensure the browser window is a set size before taking the screenshot. This helps ensure that all full window screenshots are of standard dimensions.

  • If necessary, call attention to hard to find parts of the screenshot with red outlines (border: #C00, width:1px) or with a transparent gray (#ECECEC) layer over unimportant parts of the picture.

10.4. Accessibility

  • Section 508 compliance requires that all of the information is available in a text format for accessibility reasons (for instance, screen readers can not extract information from images).

  • Also, a large number of screenshots can possibly slow download of docs for those on slow connections (rarer for most enterprises these days).

10.5. AsciiDoc syntax

  • Insert a block-level image, which uses a double colon (::). Good for screenshots, diagrams, etc.

    • Example 1: Include an image title in title case (which automatically appends a Figure #).

      .Image Title
image::icon.png[Alt text, 50, 50]

    • Example 2: Insert an inline image. Note, there is only one colon (:) used here.

      This is an inline image. image:icon.png[Alt text] Cool!

10.6. Additional questions

  • When should I add a screenshot to my book?

    • When introducing a new part of the UI.

    • When the UI is suboptimal and some elements are difficult to find, located in unusual places, hidden, or somehow less visible.

  • When, in the development cycle, should I add my screenshots?

    • Add them as late in the cycle as possible, preferably during the review process. At this late stage, hopefully there will be fewer UI changes to the product.

      Tip
      		 Add a placeholder for the screenshot early on in the development cycle. This way it will not be forgotten.

  • What image editor should I use?

    • The recommended graphical editor is GIMP.

10.7. Browser extensions

10.7.1. Resizing screenshots

There are a couple simple browser extensions that can assist in resizing your browser to the appropriate dimensions.

11. Administrating AMQ 7 documentation

This guide describes how to administer the AMQ 7 documentation GitHub and GitLab repositories. All commits, with the exception of internal resources, are to be merged weekly on Friday by the "Mergemaster".

11.1. Documentation repositories

AMQ 7 documentation uses the following documentation repositories:

amq7-documentation-contrib (GitHub)

A private GitHub repo that hosts all of the AMQ 7 documentation. All downstream contributions to the documentation are made in this repo.

amq7-docs (GitLab)

A GitLab repo for pushing doc updates to Pantheon for publication on the Red Hat Customer Portal. This repo essentially functions as a "mirror" of amq7-documentation-contrib; no doc updates should be made in it.

11.2. Branching overview

The amq7-documentation-contrib repo contains several branches, most of which are inactive or deprecated. The only ones that you need to use are:

contrib

The default branch. All doc contributions are merged into this branch, regardless of release.

master

The master branch for preparing doc builds.

release-amq-7.<version-number>.x

The branch for an AMQ 7.x.y doc release.

11.3. Processing pull requests

After a pull request has passed SME and peer review, it is ready to be merged into the contrib branch in the GitHub repo. This can be done piecemeal, but the current practice is for the "Mergemaster" to merge all pull requests on a weekly basis (Friday, 1pm EDT/EST).

11.3.1. Opening the pull request

Procedure

  1. In the amq7-documentation-contrib repo, click Pull Requests.

  2. Verify that the pull request that you want to merge has the Ready to Merge label applied.

    This label specifies that the changes in the pull request have passed SME and peer reviews.

  3. Click the pull request to open it.

11.3.2. Reviewing the pull request

Procedure

  1. Under the pull request title, verify that the pull request is being merged into rh-messaging:contrib.

  2. Review the conversation to ensure all comments have been resolved and that there are not any outstanding, glaring issues that need to be addressed.

  3. Determine if the pull request can be merged automatically, or if conflicts need to be resolved.

    If the pull request can be merged automatically, you will see This branch has no conflicts with the base branch.

11.3.3. Merge the pull request

In most cases, you should be able to merge the pull request automatically. However, if there are any conflicts, you must resolve them.

Merging the pull request automatically
Procedure

  1. Click the Squash and merge button.

    You might need to click the arrow next to Create a merge commit to select this option.

    Use the squash and merge option rather than the option to create a merge commit. Squashing the commits makes for a cleaner commit history.

  2. Click Confirm squash and merge.

    The pull request is merged into contrib and closed.

Handling a pull request with conflicts
Procedure

  1. Click Resolve conflicts to determine the extent of the conflicts.

    • If the conflict is minor, and you can easily see how to resolve it, make the change in the web editor, and then click Mark as resolved. Your changes are committed and added to the pull request.

    • If the conflict is extensive or the resolution is unclear, notify the author and ask him or her to make the necessary corrections.

      For additional information about handling complex merge conflicts, see Fix Rebase Merge Conflicts.

  2. When the conflicts are resolved, merge the pull request.

11.4. Pushing to GitLab for doc builds

The amq7-docs repo is the source for the AMQ 7 Preview, Stage, and Production environments. Therefore, to build the doc, you need to push the content from GitHub to GitLab.

11.4.1. Merge to the GitHub master branch

In amq7-documentation-contrib, you need to merge to master everything that you want to be included in the doc build.

Procedure

  1. In amq7-documentation-contrib, navigate to the Pull requests tab and then click New pull request.

  2. Click the base: contrib button and select master.

    The first button should be base: master, and the second button should be compare: contrib.

  3. Click Create pull request.

  4. In the Title field, enter a descriptive name (for example, "Doc Build").

  5. Click Create pull request.

  6. In the pull request, click Squash and merge.

    All of the commits from contrib are merged to master, and the pull request is closed.

11.4.2. Push to GitLab

After merging to master everything that you want to be in the doc build, you pull the changes down to a local branch, and then push the commits to the amq7-docs GitLab repo. After pushing to amq7-docs, Pantheon automatically builds the docs in the Preview and Stage environments.

Procedure

  1. In git, if you do not have a remote repository for amq7-docs, then add one:

    $ git remote add -f REPO_NAME git@gitlab.cee.redhat.com:AMQ7-documentation/amq7-documentation.git

    For REPO_NAME, you can use whatever name you want. For simplicity, you should probably name it amq7-docs to match the name of the actual repo.

  2. Fetch the latest from the upstream repository:

    $ git fetch upstream

  3. Do one of the following:

    Check out a new local branch based on the GitHub master branch:
    $ git checkout -b BRANCH_NAME upstream/master
    Reset an existing local branch with the GitHub master branch:
    $ git checkout BRANCH_NAME
$ git reset --hard BRANCH_NAME upstream/master

  4. Verify that the branch contains everything that you expect:

    $ git log

  5. Push the changes to the master branch on the amq7-docs repo:

    $ git push -f GITLAB_REMOTE_REPO HEAD:master

  6. If necessary, in amq7-docs, verify that everything was pushed to the master branch the way you expected.

  7. Verify that each doc builds successfully on Preview and Stage in Pantheon: https://pantheon.cee.redhat.com//titles/red_hat_amq

11.5. Preparing AMQ documentation for release

When an AMQ product release is ready, there are several tasks you must complete to prepare the documentation for the release and push it to Pantheon for publication on the customer portal.

11.5.1. Creating a release branch

When it is time to publish the AMQ docs for a release, you should create a release branch.

Procedure

  1. Create a release branch from master:

    Release branch names should follow this syntax: release-amq-7.VERSION_NUMBER.x.

    git fetch upstream
git checkout -b release-amq-7.1.x upstream/master
git push upstream HEAD:release-amq-7.1.x

  2. Push the release branch to GitLab:

    git push amq-docs HEAD:release-amq-7.1.x

  3. In Pantheon, navigate to the release.

  4. For each title, click the drop-down for the Preview branch, select Edit Configuration, and then select the release branch that you created.

  5. Repeat the previous step for the Stage branch.

11.5.2. Tagging a release

A tag represents a snapshot of the repository at a particular point in time. After creating a release branch, you should create a tag to identify exactly what was delivered for the release. If you ever need to republish the documentation on the release branch (such as for a hotfix or asynchronous doc update after the initial release), the tag will identify what was originally published.

Procedure

  1. Check out the release branch.

    git checkout release-amq-7.1.x

  2. Create the tag.

    git tag 7.1.0 -m "Release 7.1"

  3. Push the tag to the GitHub repo.

    git push upstream HEAD --tags 7.1.0

  4. In the GitHub repo, view the tag to verify that it looks correct.

11.5.3. Cherry-picking a commit to a release branch

Even though release branches are created at the end of the release process (typically immediately prior to publishing the docs on the portal), it may be necessary to update a doc in this release after the release has been published. You can do this by cherry-picking the commit to the release branch.

Procedure

  1. Merge the PR into the default branch just as you would normally do.

  2. Fetch the latest changes from GitHub:

    git fetch upstream

  3. Create a new topic branch from the release branch.

    In this example, a new branch for AMQDOC-2752 is being created for the 7.1.x release branch.

    git checkout -b amqdoc-2752 upstream/release-amq-7.1.x

  4. Using GitHub or the git log command, find the number of the commit that was merged to contrib.

  5. Cherry pick the commit into your topic branch.

    git cherry-pick cafd2a9

  6. Push the changes to your own forked repo:

    git push origin HEAD

  7. In GitHub, create a PR from your topic branch with the cherry-picked commit to the release branch.

  8. Merge the PR. Be sure to change the “base fork” to the release branch.

  9. If necessary, push to Pantheon to build the docs that are affected by the cherry-picked commit.

Appendix A: Files and attributes

A.1. Important files

Standard attributes

common/attributes.adoc

Shared includes

common/

Images

images/

A.2. Anchor names and file names

To optimize modular documentation, follow these guidelines for naming module anchors and files:

Anchor names

Provide an anchor in the format [id='anchor-name'] for every module so that it can be identified by Asciidoctor when reused or cross-referenced. Give the anchor the same or similar name as the module heading, separated by dashes:

[id='anchor-name']
= Module Heading

First sentence of topic.
Note
Note on other anchor formats (Not Recommended)

The format defined here is recommended because it is the most stable and versatile of anchor formats, and supports variables that enable topics to be reused and cross-referenced properly. Other anchor formats include [[anchor-name]] and [#anchor-name], but these formats either do not support variables for content reuse or do not support certain character types, such as periods. These limitations cause errors at build time.
File names

Give the module file the same name as the anchor used in it (which is the same as or similar to the module heading), also separated by dashes. Add a prefix with an underscore to the file name to indicate the module type in the format prefix_file-name. Use snip_ for a snippet, con_ for concept, ref_ for reference, proc_ for procedure, assembly_ for assembly, and image_ for images and screenshots.

Examples

  • snip_guided-decision-urls.adoc (Snippet of reusable content)

  • con_guided-decision-tables.adoc (Concept module)

  • proc_creating-guided-decision-tables.adoc (Procedure module for creating)

  • proc_editing-guided-decision-tables.adoc (Procedure module for editing)

  • ref_guided-decision-table-examples.adoc (Reference module with examples)

  • ref_guided-decision-table-columns.adoc (Reference module with column types)

  • assembly_guided-decision-tables.adoc (Assembly of guided decision table modules)

  • image_guided-decision-example.adoc (Screenshot or image of guided decision table modules)

Learn more in the Modular Documentation Reference Guide.

A.3. AMQ 7 books

Introduction

product-intro/master.adoc

Migration

product-migration/master.adoc

Broker

broker/master.adoc

Broker JON guide

broker-jon/master.adoc

Broker release notes

broker-release-notes/master.adoc

Interconnect

router/master.adoc

Interconnect release notes

router-release-notes/master.adoc

Client release notes

client-release-notes/master.adoc

Console

console/master.adoc

AMQ JMS Client

client-amqp-jms/master.adoc

AMQ C++ Client

client-amqp-cpp/master.adoc

AMQ JavaScript Client

client-amqp-javascript/master.adoc

AMQ Python Client

client-amqp-python/master.adoc

AMQ .NET Client

client-amqp-dotnet/master.adoc

OpenWire JMS Client

client-openwire-jms/master.adoc

A.4. Standard attributes

{ProductLongName}

Long product name

Red Hat AMQ

{ProductName}

Short product name

AMQ

{ProductVersion}

Product X.Y version

7.1

{ProductMajorVersion}

Product X version

7

{BrokerCoreBridge}

Core bridge name

Core Bridge

{BrokerLongName}

Long broker name

Red Hat AMQ Broker

{BrokerName}

Short broker name

AMQ Broker

{BrokerVersion}

Broker X.Y version

7.1

{RouterLongName}

Long router name

Red Hat AMQ Interconnect

{RouterName}

Short router name

AMQ Interconnect

{RouterVersion}

Router X.Y version

1.1

{ClientsLongName}

Long clients name

Red Hat AMQ Clients

{ClientsName}

Short clients name

AMQ Clients

{ClientsVersion}

Clients X.Y version

2.0

{ConsoleLongName}

Long console name

Red Hat AMQ Console

{ConsoleName}

Short console name

AMQ Console

{ConsoleVersion}

Console X.Y version

1.0

{ClientAmqpJmsName}

AMQP JMS client name

AMQ JMS

{ClientAmqpCppName}

AMQP C++ client name

AMQ C++

{ClientAmqpPythonName}

AMQP Python client name

AMQ Python

{ClientAmqpJavaScriptName}

AMQP JavaScript client name

AMQ JavaScript

{ClientAmqpDotNetName}

AMQP .NET client name

AMQ .NET

{ClientCoreJmsName}

Core Protocol JMS client name

AMQ Core Protocol JMS

{ClientOpenWireJmsName}

OpenWire JMS client name

AMQ OpenWire JMS

Appendix B: Git tips

B.1. Deleting branches

To delete all of your branches except the branch you are on:

$ git checkout contrib
$ for br in `git branch` ; do git branch -D $br ; done

To delete one branch:

$ git checkout contrib
$ git branch -D BRANCH_NAME

B.2. Resolving conflicts

To resolve a merge conflict in an existing pull request:

$ git checkout BRANCH_NAME
$ git branch -u origin BRANCH_NAME
$ git pull --rebase upstream contrib
$ git push -f origin HEAD

B.3. Reseting your fork

If your fork is both ahead of and behind the origin you can reset your fork to match the origin and start with a clean slate.

$ git checkout contrib
$ git reset --hard upstream/contrib
$ git push origin contrib --force
$ git pull upstream contrib
$ git push origin contrib --force

B.4. Accessing another writer’s unmerged commits

This is the process you can use if you need commits another writer has submitted in a merge request that is not yet merged.

  1. Make sure you are on the contrib branch

    $ git checkout contrib

  2. Check out a new topic branch from upstream/contrib as you normally do.

    $ git fetch upstream
$ git checkout -b NEW_TOPIC_BRANCH upstream/contrib

  3. If you have not yet added that writer’s remote repository, add it now.

    $ git remote add -f USER git@github.com:USER/amq7-documentation-contrib.git

  4. Rebase to bring in the changes that are in that user’s outstanding origin/MERGE_REQUEST_BRANCH branch.

    $ git rebase USER/MERGE_REQUEST_BRANCH

    (you will see the following response)

    First, rewinding head to replay your work on top of it...
Fast-forwarded NEW_TOPIC_BRANCH to USER/MERGE_REQUEST_BRANCH

B.4.1. Committing to another writer’s branch

If you have made changes to the content in someone else’s branch you’ll want to be sure to commit them back to that same branch/PR.

  1. While in your working branch, commit your changes

    $ git commit -m "MESSAGE"

  2. Push your changes to the existing PR

    $ git push USER HEAD:MERGE_REQUEST_BRANCH

Appendix C: Templates

The following templates must be used to produce consistent modular documentation for AMQ 7. Download the adoc files in zip format.

C.1. Doing one procedure

This paragraph is the procedure module introduction: a short description of the procedure.

Prerequisites

  • A bulleted list of conditions that must be satisfied before the user starts following this assembly.

  • You can also link to other modules or assemblies the user must follow before starting this assembly.

  • Delete the section title and bullets if the assembly has no prerequisites.

Procedure

  1. Start each step with an active verb.

  2. Include one command or action per step.

  3. Use an unnumbered bullet (*) if the procedure includes only one step.

Additional Resources

C.2. Concept explanation

This paragraph is the concept module introduction and is only optional. Include it to provide a short overview of the module.

The contents of a concept module give the user descriptions and explanations needed to understand and use a product.

  • Look at nouns and noun phrases in related procedure modules and assemblies to find the concepts to explain to users.

  • Explain only things that are visible to users. Even if a concept is interesting, it probably does not require explanation if it is not visible to users.

  • Do not include any instructions to perform an action, such as executing a command. Action items belong in procedure modules.

Additional resources

C.3. Reference material

This paragraph is the reference module introduction and is only optional. Include it to provide a short overview of the module.

A reference module provide data that users might want to look up, but do not need to remember. It has a very strict structure, often in the form of a list or a table. A well-organized reference module enables users to scan it quickly to find the details they want. AsciiDoc markup to consider for reference data:

Unordered lists
Labeled lists
Term 1

Definition

Term 2

Definition

Table 8. Tables
Column 1 Column 2 Column 3

Row 1, column 1

Row 1, column 2

Row 1, column 3

Row 2, column 1

Row 2, column 2

Row 2, column 3

Appendix D: Additional resources

Unresolved directive in master.adoc - include::common/revision-info.adoc[]