Skip to content

Commit

Permalink
Add workaround for linebreaks Confluence Cloud bug (#72)
Browse files Browse the repository at this point in the history
* Add workaround for linebreaks Confluence Cloud bug

This commit adds a workaround for #71, just for the Gauge specs in this
gauge-confluence repo.  The workaround is not to have any line breaks in
any paragraphs in the Gauge specs.

* Bump plugin patch version
  • Loading branch information
johnboyes authored Oct 23, 2021
1 parent 1804e99 commit c5b22eb
Show file tree
Hide file tree
Showing 9 changed files with 16 additions and 42 deletions.
7 changes: 2 additions & 5 deletions functional-tests/specs/delete_specs_before_publishing.spec
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,10 @@
tags: create-space-manually

## The plugin deletes all existing published specs before publishing
It is safe to do this as before doing so we abort if the Space has been manually edited since the last publish.
NB The Space homepage is not deleted, it is just the published specs that are deleted (i.e. all the other pages
in the Space apart from the homepage).
It is safe to do this as before doing so we abort if the Space has been manually edited since the last publish. NB The Space homepage is not deleted, it is just the published specs that are deleted (i.e. all the other pages in the Space apart from the homepage).

* Publish "26" specs to Confluence
The default limit for pagination on the Confluence API is 25, so we publish 26 specs here to ensure that the
plugin handles pagination correctly when deleting the specs on the second publish below.
The default limit for pagination on the Confluence API is 25, so we publish 26 specs here to ensure that the plugin handles pagination correctly when deleting the specs on the second publish below.

* Publish specs to Confluence:

Expand Down
16 changes: 4 additions & 12 deletions functional-tests/specs/dry_run.spec
Original file line number Diff line number Diff line change
@@ -1,17 +1,10 @@
# Dry run mode

Having a dry run mode is very useful, e.g. in a CI/CD pipeline the dry run mode can be run on feature branches and pull
requests to verify that the Gauge specs are in a valid state for publishing. If they are not valid then the CI/CD
pipeline build can fail, alerting the submitter of the pull request to amend them on the feature branch. This ensures
that the Gauge specs are always in good shape to be automatically published by the CI/CD pipeline upon any push to the
trunk branch (e.g. upon a successful pull request merge).
Having a dry run mode is very useful, e.g. in a CI/CD pipeline the dry run mode can be run on feature branches and pull requests to verify that the Gauge specs are in a valid state for publishing. If they are not valid then the CI/CD pipeline build can fail, alerting the submitter of the pull request to amend them on the feature branch. This ensures that the Gauge specs are always in good shape to be automatically published by the CI/CD pipeline upon any push to the trunk branch (e.g. upon a successful pull request merge).

The Gauge Confluence plugin will exit with a non-zero exit code if the dry run finds that any specs are not in a valid
state for publishing. This means that the CI/CD pipeline can use the exit code (0 for success, not 0 for fail) to pass
or fail the dry run build (and indeed the actual build too, when not running in dry run mode).
The Gauge Confluence plugin will exit with a non-zero exit code if the dry run finds that any specs are not in a valid state for publishing. This means that the CI/CD pipeline can use the exit code (0 for success, not 0 for fail) to pass or fail the dry run build (and indeed the actual build too, when not running in dry run mode).

The dry run mode is set by setting a `DRY_RUN` [environment variable or property][1] with the value `true` (we can't
use a command-line flag for this as [Gauge does not propagate command line flags to documentation plugins][2]).
The dry run mode is set by setting a `DRY_RUN` [environment variable or property][1] with the value `true` (we can't use a command-line flag for this as [Gauge does not propagate command line flags to documentation plugins][2]).


|spec 1 heading|spec 2 heading|did dry run succeed?|message |
Expand All @@ -38,8 +31,7 @@ Tags: create-space-manually


## Dry run mode does not require the Confluence Space to exist yet
The absence of the "create-space-manually" tag means the Confluence Space does not
exist for this scenario
(The absence of the "create-space-manually" tag means the Confluence Space does not exist for this scenario)

* Activate dry run mode

Expand Down
12 changes: 4 additions & 8 deletions functional-tests/specs/duplicate_scenario_headings.spec
Original file line number Diff line number Diff line change
@@ -1,14 +1,10 @@
# Duplicate spec headings and directory names
Tags: create-space-manually

The page title for every page in a Confluence space must be unique.
We use the specification heading as the Confluence page title.
And for directories we use the directory name as the Confluence page title.
So this means that there can be no duplicates among the spec headings and directory names.
NB the spec filenames are not relevant, it's just the spec headings and the directory names which must be unique.
tags: create-space-manually

This table shows examples with two specifications, as there needs to be at least two specs for there to be a
chance of duplicate spec headings.
The page title for every page in a Confluence space must be unique. We use the specification heading as the Confluence page title. And for directories we use the directory name as the Confluence page title. So this means that there can be no duplicates among the spec headings and directory names. NB the spec filenames are not relevant, it's just the spec headings and the directory names which must be unique.

This table shows examples with two specifications, as there needs to be at least two specs for there to be a chance of duplicate spec headings.

|spec 1 heading|spec 1 path |spec 2 heading|spec 2 path |did publishing occur?|message |
|--------------|-------------|--------------|-----------------|---------------------|----------------------------------------------|
Expand Down
3 changes: 1 addition & 2 deletions functional-tests/specs/homepage.spec
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,7 @@ Tags: create-space-manually

* Publish "1" specs to Confluence

The version number is 2 after the initial publish because the plugin immediately updates the homepage that
was initially created with default content when the space was created by the plugin, on the same plugin run.
The version number is 2 after the initial publish because the plugin immediately updates the homepage that was initially created with default content when the space was created by the plugin, on the same plugin run.
* Homepage version number is "2"

* Publish "1" specs to Confluence
Expand Down
3 changes: 1 addition & 2 deletions functional-tests/specs/publish_specs.spec
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,7 @@
tags: create-space-manually

## All specs are published, including those in subdirectories
The specs are published to Confluence as a page tree, mirroring the directory structure of the specs. This means that
as well as a Confluence page being created for each spec, a page is also created for each directory.
The specs are published to Confluence as a page tree, mirroring the directory structure of the specs. This means that as well as a Confluence page being created for each spec, a page is also created for each directory.

* Publish specs to Confluence:

Expand Down
3 changes: 1 addition & 2 deletions functional-tests/specs/publish_specs_from_different_dir.spec
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,7 @@

tags: create-space-manually

Gauge documentation plugins allow for any directory containing specs to be specified
as a command-line argument to the plugin.
Gauge documentation plugins allow for any directory containing specs to be specified as a command-line argument to the plugin.

## Publish from a different directory than the default specs directory

Expand Down
4 changes: 1 addition & 3 deletions functional-tests/specs/space_creation.spec
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,7 @@

* Space has name "Gauge specs for example-user/example-repo"

The `example-user/example-repo` comes from the [dummy Git remote URL config in the
test framework code][1]. When users run the plugin the Space name will be taken from
the Git remote URL of the Git repository that the plugin is executed on.
The `example-user/example-repo` comes from the [dummy Git remote URL config in the test framework code][1]. When users run the plugin the Space name will be taken from the Git remote URL of the Git repository that the plugin is executed on.

* Output contains "Success: published 2 specs and directory pages to Confluence Space named: Gauge specs for example-user/example-repo"

Expand Down
8 changes: 1 addition & 7 deletions functional-tests/specs/space_validity.spec
Original file line number Diff line number Diff line change
@@ -1,13 +1,7 @@
# Confluence Space validity
Tags: create-space-manually

This Gauge Confluence plugin requires that the specs for a given Gauge project are published to
their own dedicated [Confluence Space][1], with no manual edits or additions in Confluence.
Having the Space only contain published Gauge specs ensures that there is no danger of the plugin
inadvertently overwriting or deleting manually created Confluence pages.
NB The specs can still appear alongside your existing manually created Confluence documentation
in other spaces, by using Confluence's [Include Page macro][2]. This macro
[allows you to include the full page tree of specs in as many other spaces as you like][3].
This Gauge Confluence plugin requires that the specs for a given Gauge project are published to their own dedicated [Confluence Space][1], with no manual edits or additions in Confluence. Having the Space only contain published Gauge specs ensures that there is no danger of the plugin inadvertently overwriting or deleting manually created Confluence pages. NB The specs can still appear alongside your existing manually created Confluence documentation in other spaces, by using Confluence's [Include Page macro][2]. This macro [allows you to include the full page tree of specs in as many other spaces as you like][3].


## Publishing is aborted if the Space has been manually edited since the last publish
Expand Down
2 changes: 1 addition & 1 deletion plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"id": "confluence",
"version": "0.18.3",
"version": "0.18.4",
"name": "Confluence",
"description": "Publishes Gauge specifications to Confluence",
"install": {
Expand Down

0 comments on commit c5b22eb

Please sign in to comment.