internal_howto_release

Introduction
Before publishing:
HowTo release the Maven Plugin
- Configure the git credentials
- Execute the release
How to release the Gradle Plugin
HowTo update the wiki
- As a project
- Update of the TOC (Table Of Content)
HowTo publish the site
- Configuring the domain name
- Generating the site

Introduction

This page is more an internal howto, to remind of the step to:

Release the Maven plugin
Release the Gradle plugin
Publish the project web site, as publishing a site is really complex, from the maven-site-plugin, to the github configuration to use a specific domain, through the issue of the multi-module stuff.

And of course, if it can be useful for anyone to publish a site, then, it's nice! :)

Before publishing:

Check that the user has access on the owner of the git repository, as the last step works only if connected on githib with the owner of the repository.
Check the TODO list: some done work may still be on the TODO list.
Update the CHANGELOG.md:
- Check the version for the updates being released
- Check that all the done job is described

HowTo release the Maven Plugin

Configure the git credentials

The pom.xml file declares a property project.scm.id which value is git-graphql-java-generator.

So the maven settings.xml must contain a definition for this server:

	<servers>
...
		<server>
			<id>git-graphql-java-generator</id>
			<username>{{login for github}}</username>
			<password>{{password for github}}</password>
		</server>
...
	</servers>

Where the password is a token declared in github:

Go to the github user's settings page (click on the icon on the top right of the github screen, then settings)
Then on the bottom left, click on developper settings
Then create a new token.
The associated login is your login (typically: your email)

Execute the release

Execute to execute the release on GitHub:

mvn release:clean release:prepare

Take care to:

Give the proper version for the release
Let the default value for the tag (so that all tags look the same)
Give local-SNAPSHOT as the next version. This allows very easy comparison between the commits in git

Then, in order to publish the release toward the maven central repository:

mvn release:perform

Once this command succeeds, the maven plugin should be stored in the OSSRH repository, waiting to be replicated into the central repository. This can be checked by browsing into it: https://repo1.maven.org/maven2/com/graphql-java-generator/graphql-maven-plugin/.

At the end of the process, the plugin is available in the OSSRH repository. It will then be published into the central Maven repository. This last step can be long (up to several hours).

This can be checked by accessing directly to the good page:

How to release the Gradle Plugin

Configure the project

You'll first have to change the plugin's version:

Open the graphql-gradle-plugin/common_conf.gradle file
Change the project version to the plugin's version to publish. The Maven plugin of this version must be available in maven repository (either local or central)

Adapt the plugin code, if things have changed due to changed in the plugin-logic module
Configure the global gradle.properties

In order to make this work, you need to update the .gradle/gradle.properties file, and add these lines:

systemProp.http.proxyHost=...
systemProp.http.proxyPort=...
systemProp.https.proxyHost=...
systemProp.https.proxyPort=...

# Properties for the graphql-gradle-plugin-project project
systemProp.graphqlGradlePlugin.graphqlMavenPluginProject.path=path_of/graphql-maven-plugin-project

# Gradle publish keys for the https://plugins.gradle.org site, for graphql-java-generator
gradle.publish.key=...
gradle.publish.secret=...

Copy the samples

Copy the code and resources for the samples, from the maven project:

From the root of the Gradle project, execute:

gradlew copySamplesFromMavenPlugin

[not always] Adapt the dependencies version(see the graphql-gradle-plugin/common_conf.gradle file)
[not always] Adapt the build.gradle files, for instance if some plugin options have changed in the samples
Build the whole project

From the root of the Gradle project, execute:

gradlew cleanAll build

Test the plugin locally

Test the plugin by using a local publication

The plugin is configured with a local maven repository in the graphql-gradle-plugin/build/local-plugin-repository folder, thanks to:

The maven publish plugin
These configuration lines in the plugins's build.gradle file:

publishing {
    repositories {
        maven {
            name = 'localPluginRepository'
            url = 'build/local-plugin-repository'
        }
    }
}

To publish the plugin into this local plugin repository:

gradlew publishAllPublicationsToLocalPluginRepositoryRepository

Then to use the plugin in a local project, you'll have to add on the top of its settings.gradle file these lines:

pluginManagement {
    repositories {
        maven {
            url = '../graphql-gradle-plugin-project/graphql-gradle-plugin/build/local-plugin-repository'
        }
        gradlePluginPortal()
    }
}

Of course, you'll may have to change the path, according to your configurarion. This configuration if both the graphql-gradle-plugin-project and your local test project are in the same folder, for instance your git folder, where all your git projects are locally copied. This will be the case if you check out on of the gradle tutorials: the graphql-maven-plugin-samples-Forum-client or graphql-maven-plugin-samples-Forum-server

Publish the plugin

Create and push the git tag

You can copy/paste what's changed in the tag comment

Publish the plugin

Don't forget to check the project's version

From the graphql-gradle-plugin folder then from the graphql-gradle-plugin3 one (or since 2.4 or directly from the root folder), execute:

gradlew publishPlugins

HowTo update the wiki

As a project

The wiki pages contains lots of doc about the plugin. It can be check out at this url: https://github.com/graphql-java-generator/graphql-maven-plugin-project.wiki.git, but this url isn't accessible on the github site.

Update of the TOC (Table Of Content)

github doesn't seem to provide a TOC macro. The gh-md-toc, in the root of the wiki project, is a copy of the github-markdown-toc script provided by ekalinin.

This script has been updated, with one line commented and changed:

#etienne_sf: update to work on the github wiki pages
#                   print sprintf("%*s", (level-1)*'"$2"', "") "* [" text "](" gh_url  modified_href ")"
                    print sprintf("%*s", (level-1)*'"$2"', "") "* [" text "](" modified_href ")"

And one commented line:

# etienne_sf: the line below is commented, to avoid to see changes, when only the execution date changed
#            toc_footer="<!-- Added by: `whoami`, at: `date` -->"

HowTo publish the site

Configuring the domain name

The standard way of publishing a web site on github, is to push the site on the gh-pages branch of the project. Then, check the settings of the project. At this stage, the project site is available at this URL: https://graphql-java-generator.github.io/graphql-maven-plugin-project/.

It's possible to define a custom domain in the settings.

On the DNS configuration for the graphql-java-generator.com domain, let's add this line:

graphql-maven-plugin-project 1800 IN CNAME graphql-java-generator.github.io.

And in the settings, define the Custom domain to be: graphql-maven-plugin-project.graphql-java-generator.com

Then, the project site is available at https://graphql-maven-plugin-project.graphql-java-generator.com with the site published on the gh-pages branch of the project.

Generating the site

The use of maven-site-plugin is complex, but well described.

Here are the steps to execute:

cd target/checkout

This allows to go to the just performed release, and get all the code in the relevant version

publish_site

which is a Windows command file, that wraps:

mvn antrun:run -Prelease
git push

This script asks for the release version. But it seems that this entry is not taken into account. Only the project version is used.

Thanks to the CNAME file being preserved, in the ant file, the custom domain configuration should not disappear... But it may be worth a check, to get to the settings of the project, to restore the custom domain, which is graphql-maven-plugin-project.graphql-java-generator.com