You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This repository contains the official documentation for the [eXist-db native XML database](http://www.exist-db.org) and the application for browsing it. You can browse the latest release of the documentation on [eXist-db homepage](http://exist-db.org/exist/apps/doc/). User reporting errors should check the [contributions](#contributions) section below. Core-contributors preparing a release should consult the [release procedure](RELEASE.md)
8
9
9
-
- Browse the latest release of the documentation at http://exist-db.org/exist/apps/doc/.
10
-
- The documentation app is included by default in the eXist-db installer. Just go to your eXist server's Dashboard and select Documentation.
11
-
- Update to the latest release via the eXist-db package manager or via the eXist-db.org public app repository at <http://exist-db.org/exist/apps/public-repo/>.
4. An EXPath Application Package (.xar file) is deposited in the `target` directory
11
+
## Dependencies
12
+
-[Maven](https://maven.apache.org): 3.x
13
+
-[eXist-db](http://exist-db.org): 3.5.0
30
14
31
-
5. Install this file via the Dashboard > Package Manager.
15
+
## Installation
16
+
- The default eXist-db installer includes the documentation app. Just go to your eXist server's Dashboard and select Documentation.
17
+
- If you need to install an older version, you can download EXPath Application Packages (`.xar` files) of previous [releases](https://github.com/eXist-db/documentation/releases) from GitHub.
18
+
- Update to the latest release via the eXist-db package manager or via the eXist-db.org public app repository at [http://exist-db.org/exist/apps/public-repo/](http://exist-db.org/exist/apps/public-repo/).
32
19
33
-
Find an area of the documentation that needs to be improved? Please raise an issue and submit a pull request!
20
+
## Contributions
21
+
Found an area of the documentation that needs to be improved? Please raise an [issue](https://github.com/eXist-db/documentation/issues) or better yet submit a [pull request](https://github.com/eXist-db/documentation/pulls)!
34
22
23
+
Our test-suite performs a validation check on all articles when you open a pull request. You can speed up the review process by running `mvn validate` locally before submitting a pull request.
35
24
36
-
## Building a Release from source
37
-
38
-
1. Follow the instructions from [Building from source](#building-from-source)
39
-
40
-
2. Create a Release:
41
-
42
-
```bash
43
-
$ mvn release:prepare
44
-
$ mvn release:perform
45
-
```
46
-
47
-
3. An EXPath Application Package (.xar file) is deposited in the `target` directory
48
-
49
-
4. If you are a core contributor, you should then commit and push.
Core-contributors should follow these steps when publishing a new release of the documentation app.
3
+
4
+
## Local Environment Checks
5
+
- maven requires a valid gpg key associated with your GitHub account to publish a new release, to check your available keys:
6
+
```bash
7
+
gpg --list-keys
8
+
```
9
+
- You can perform a dry-run of the release procedure by executing
10
+
```bash
11
+
$ mvn -DdryRun=true release:prepare
12
+
```
13
+
- Dry-runs still create files that will interfere with regular releases. You should therefore clean up afterwards by running:
14
+
```bash
15
+
$ mvn release:rollback
16
+
```
17
+
18
+
19
+
## Preparing the Release Commit
20
+
1. Merge outstanding and reviewed PRs.
21
+
22
+
2. Set the `exist.version` in `pom.xml` to prevent users of older exist releases, from installing the wrong documentation locally. Since the canonical version needs to run on exist-db.org please make sure that the main server can actually run the latest documentation, and raise an issue if necessary.
23
+
24
+
3. To generate the release notes run:
25
+
```bash
26
+
$ mvn changes:github-report
27
+
```
28
+
29
+
this will generate a `github-report.html` in `target/site` you can copy the list of changes into `xar-assembly.xml` describing which articles changed and how.
30
+
31
+
## Building the Release
32
+
4. Follow the instructions from [Building from source](README.md#building-from-source)
33
+
34
+
5. To create a release run:
35
+
```bash
36
+
$ mvn release:prepare
37
+
$ mvn release:perform
38
+
```
39
+
40
+
When prompted to pick a version number for the release, remember to mirror the [major version](https://github.com/eXist-db/exist/blob/develop/exist-versioning-release.md#versioning-scheme) of the current eXist-db release. So for exist-db version `3.x.x` the documentation's version should be `3.y.y`. The minor and patch numbers remain independent of each other.
41
+
42
+
You can find the EXPath Application Package (`.xar` file) for the release in the `/target` directory
43
+
44
+
## Publishing the Release
45
+
Release are published in two locations:
46
+
47
+
6. GitHub: Repo and [releases](https://github.com/eXist-db/documentation/releases)
48
+
- commit and push as usual
49
+
- maven should have automatically created a release tag, update it by copying the release notes from `xar-assembly.xml`
50
+
- check to make sure that the latest `.xar` file is attached to the GitHub release
51
+
52
+
7.[exist-db.org](http://exist-db.org): App repo and documentation homepage
53
+
- Inform the exist-db.org admins that the documentation app should be deployed on the server.
54
+
- Add documentation app to the public application repository.
Copy file name to clipboardExpand all lines: src/main/xar-resources/data/upgrading.xml
+19-19Lines changed: 19 additions & 19 deletions
Original file line number
Diff line number
Diff line change
@@ -30,7 +30,7 @@
30
30
</section>
31
31
<sectionid="binary-compatible-upgrades">
32
32
<title>Binary Compatible Upgrades</title>
33
-
<para>Follow these steps if the new version of eXist is binary-compatible with the your old version. Check the new version's release notes to find out whether it is binary compatibility with your old version.</para>
33
+
<para>Follow these steps if the new version of eXist is binary-compatible with the your old version. Check the new version's release notes to find out whether it is binary compatible with your old version.</para>
34
34
<procedure>
35
35
<step>
36
36
<para>Stop the old installation of eXist, if it is running.</para>
@@ -39,14 +39,14 @@
39
39
<para>Create a <ulinkurl="backup.xml">backup</ulink> of the data from your old installation of eXist.</para>
40
40
</step>
41
41
<step>
42
-
<para>Install the new version of eXist. Do not install one eXist version over another one.
42
+
<para>Install the new version of eXist. Do not install one eXist version over another one.
43
43
Always install the new version into a fresh new directory.</para>
44
44
</step>
45
45
<step>
46
-
<para>Remove the <emphasis>empty</emphasis> <code>data</code> directory from the new installation.
47
-
Typically the data directory is located in <code>webapp/WEB-INF/data</code>.
48
-
If you are not sure where the data directory is located,
49
-
you can check the <ulinkurl="troubleshooting.xml#logs"><code>exist.log</code></ulink>,
46
+
<para>Remove the <emphasis>empty</emphasis> <code>data</code> directory from the new installation.
47
+
Typically the data directory is located in <code>webapp/WEB-INF/data</code>.
48
+
If you are not sure where the data directory is located,
49
+
you can check the <ulinkurl="troubleshooting.xml#logs"><code>exist.log</code></ulink>,
50
50
searching for entires after startup pertaining to <code>DATA_DIR</code>.
51
51
</para>
52
52
</step>
@@ -63,10 +63,10 @@
63
63
</section>
64
64
<sectionid="non-binary-compatible-upgrades">
65
65
<title>Binary Non-compatible Upgrades</title>
66
-
<para>Follow these steps if the new version of eXist is not binary-compatible with the your old version.
67
-
(Check the new version's release notes to find out whether it is binary compatibility with your old version.)
68
-
Additional steps are required when upgrading to a new version of eXist whose database format is not binary-compatible with your old installation.
69
-
The key difference is that you must perform a <emphasis>full restore</emphasis> of your backed up data onto the new installation of eXist,
66
+
<para>Follow these steps if the new version of eXist is not binary-compatible with the your old version.
67
+
(Check the new version's release notes to find out whether it is binary compatibility with your old version.)
68
+
Additional steps are required when upgrading to a new version of eXist whose database format is not binary-compatible with your old installation.
69
+
The key difference is that you must perform a <emphasis>full restore</emphasis> of your backed up data onto the new installation of eXist,
70
70
rather than simply copying the data directory to the new installation.</para>
71
71
<procedure>
72
72
<step>
@@ -76,7 +76,7 @@
76
76
<para>Use Backup Central from the Dashboard (with "Zip" option for databases with less then 4GB)</para>
77
77
</listitem>
78
78
<listitem>
79
-
<para>The Emergency Backup Tool (GUI) for installer based systems:</para>
79
+
<para>The Emergency Backup Tool (GUI) for installer based systems:</para>
80
80
<programlistinglanguage="shell">java -jar start.jar -Xmx2048m org.exist.backup.ExportGUI</programlisting> <!--listing in backup.xml has no -Xmx parameter DP-->
81
81
</listitem>
82
82
<listitem>
@@ -93,10 +93,10 @@
93
93
</listitem>
94
94
</orderedlist>
95
95
</para>
96
-
<para>Once the backup is complete, you should check the backup report in the <code>export</code> directory
97
-
within either the data directory (for backups created via the Dashboard, or Xquery) or
96
+
<para>Once the backup is complete, you should check the backup report in the <code>export</code> directory
97
+
within either the data directory (for backups created via the Dashboard, or Xquery) or
98
98
<code>$EXIST-HOME</code> (for Backups created by the Emergency Backup Tool).</para>
99
-
<para>Normally this just contains the list of collections which were backed up. If you see any warnings or errors,
99
+
<para>Normally this report just contains the list of collections which were backed up. If you see any warnings or errors,
100
100
it is especially important that you perform a “full restore” of your backed-up data onto the new installation of eXist.</para>
101
101
</step>
102
102
<step>
@@ -120,14 +120,14 @@
120
120
<tgroupcols="2">
121
121
<tbody>
122
122
<tr>
123
-
<td>3.6</td>
124
-
<td><ulinkurl="http://exist-db.org/exist/apps/wiki/blogs/eXist/">release notes</ulink></td> <!--needs update with next breaking release DP-->
0 commit comments