src/site/asciidoc/developers/publishing-site.adoc

= Archiva Site Publishing
Martin Stockhammer <martin_s@apache.org>
2019-11-30
:toc:

== General information about the site publish process

The archiva site is built from multiple different more or less independent modules. The build process
uses `maven-site-plugin` for generating the static HTML pages and stylesheets and `scm-publish-plugin` for
publishing the results to the repository.

The generated HTML pages are stored at a git repository:
https://gitbox.apache.org/repos/asf?p=archiva-web-content.git[`archiva-web-content.git`].

The git repository contains a `.asf.yaml` file that defines the branch `asf-staging` as staging branch. The
master branch is used by git-pub-sub to publish the official archiva site at https://archiva.apache.org .

If you push something to the `asf-staging` branch you can see the changes immediately at https://archiva.staged.apache.org

The maven site report and publishing plugins are configured to deploy the the asf-staging branch. That means the
overall publishing process is the following:

- Generate the site content for a module by using the scripts / maven
- Use the maven publish plugin to push the generated pages to the asf-staging branch of archiva-web-content.git
- Check the generated content at https://archiva.staged.apache.org/
- If the result is fine, release the new content by merging the content from `asf-staging` to the `master` branch

For all modules there exists a script that runs all the steps (apart from the check on the staged site). Currently
the script runs only on Linux / Bash. For details see below.

== Where is site content generated?

The Archiva site is generated from the following components:

[role="bodyTable"]
|===
|Component |Content |Git Repository |Path inside Repo |Publish Path |Skript

|Archiva Site
|Main Pages, like index.html. General information.
|https://gitbox.apache.org/repos/asf?p=archiva-site.git[`archiva-site.git`]
|/
|/
|`deploySite.sh`

|Archiva Documentation
|Archiva User Documentation. Archiva Configuration.
|https://gitbox.apache.org/repos/asf?p=archiva.git[`archiva.git`]
|/archiva-docs
|/docs/${project.version}
|`archiva-docs/deploySite.sh`

|Archiva Reference Documentation
|Developer documentation for Archiva, API Javadoc pages. Information for each maven module.
|https://gitbox.apache.org/repos/asf?p=archiva.git[`archiva.git`]
|/archiva-modules
|/ref/${project.version}
|`archiva-modules/deploySite.sh`

|Redback Site
|Pages for Redback. General information about redback.
|https://gitbox.apache.org/repos/asf?p=archiva-redback-site.git[`archiva-redback-site.git`]
|/
|/redback
|`deploySite.sh`

|Redback Reference Documentation
|Developer documentation for Redback, API Javadoc pages. Information for each maven module.
|https://gitbox.apache.org/repos/asf?p=archiva-redback-core.git[`archiva-redback-core.git`]
|/
|/core/${project.version}
|`deploySite.sh`

|Archiva Component Documentation
|Information about the Archiva Components
|https://gitbox.apache.org/repos/asf?p=archiva-components.git[`archiva-components.git`]
|/
|/components
|`deploySite.sh`

|===


== Tasks for publishing

=== Using the script (Linux/Bash)

The easiest way is always to use the script `deploySite.sh` in the directory of the corresponding repository.

----
cd <path inside repo for component>
./deploySite.sh
...
...
*****************************************
>>>> Finished the site stage process <<<<
> You can check the content in the folder target/staging or by opening the following url
> file:///archiva/archiva-modules/target/staging/ref/3.0.0-SNAPSHOT/index.html
>
> If everything is fine enter yes. After that the publish process will be started.
Do you want to publish (yes/no)? yes
----

When this output is shown you can check the staging output for this component only on the given path.

If you enter `y` or `yes` here, the content will be pushed to the `asf-staging`-branch at `archiva-web-content.git`
If you enter any other key, the process will be aborted.

After the page was pushed to the `asf-staging`-branch, you can check the result at https://archiva.staged.apache.org/

[NOTE]
====
If you would like to check the page with a local clone of archiva-web-content.git you can run the script with:

 ./deploySite.sh -DsiteRepositoryUrl=scm:git:file:///${path-to-your-local-archiva}/archiva-web-content.git
====


If the result on the staged URL is fine you have to merge the branch to the master branch:

----
# git clone https://gitbox.apache.org/repos/asf/archiva-web-content.git
cd archiva-web-content
git checkout master
git merge --ff-only asf-staging
git push
----

=== Run the process manually
==== Generating Site Pages for a component


The script basically runs

 mvn clean site
 mvn site:stage

The pom.xml has a plugin definition to checkout the repository as sparse checkout to a local directory `.site-content`
The patterns for the sparse checkout are stored in the file `git-sparse-checkout-pattern`

The content of the module and all submodules is put to the directory `target/staging/${Component Path}`


==== Publishing to the staging branch

This is the part that is run, when you answer `y` or `yes` for publishing.

  mvn scm-publish:publish-scm

This checks the differences in .site-content and pushes the differences to the `asf-staging` branch.


== Information about Maven / Script configuration

There are some properties in the pom.xml that are used by the deploySite.sh. You should always make sure, that
these properties are set to the corresponding values for the given module:

- <scmPubCheckoutDirectory>.site-content</scmPubCheckoutDirectory>: The directory for the sparse checkout
- <scmPublishBranch>asf-staging</scmPublishBranch>: The staging branch
- <scmPublishPath>/</scmPublishPath>: The path relative to the base URL where the content is placed

The helper script `checkoutSite.sh` is used for running the sparse checkout of the content.

For multi-module projects the CSS (site.css) is always relative to the module directory. Therefore, we have
a link to the stylesheet at `/css/site.css` in `site.xml`


== Information about site generation

Most content is written in apt and xdoc. New documentation can/should be written in asciidoc. Asciidoc needs some css modification
to get the styles right. So please check the generated content before publishing it.

For multi-module builds you should add the central `/css/site.css` to the `<head>`-Section in `site.xml`. Because submodules
include only their own site.css and not the parent stylesheets. This can be done with:
----
<head>
        ...
        <![CDATA[    <link rel="stylesheet" href="/css/site.css" type="text/css" >]]>
        ...
</head>
----