bernardo-mg / library-maven-archetype Goto Github PK

View Code? Open in Web Editor NEW

8.0 3.0 3.0 1.03 MB

Maven Archetype to ease the creation of new Java libraries.

License: MIT License

Java 100.00%

maven-archetype template

library-maven-archetype's Introduction

Library Maven Archetype

A Maven Archetype for generating new Maven-based libraries, fully prepared to take advantage of a CI process.

While it can be prepared for any CI service, it is prepared for Github Workflow. Acquiring the code from a Github repository and publishing into OSS Sonatype or Github packages.

After running all the tests artifacts will be published into this repository, but the new project will be able to generate and publish also a Maven site, which, thanks to the Docs Maven Skin, will show documentation and useful reports from Checkstyle, SpotBugs and similar tools.

The Archetype will do little more than take care of configuration, setting up the POM and the Maven project is most of its job, and so it will include few files not related to this. Some useful things such as a readme, a gitignore and a license files are included, but the initial code will consists just of a few placeholder classes.

Features

Fully configured POM, extending from bernardomg's Base POM, including features such as build validation, changes report or manifest configuration.
Prepared for continuous integration with Github, Github Workflow and both OSS Sonatype and Github packages. Making a distinction between releases and development versions.
Prepared for unit and integration tests suites. Created with JUnit and ready to be run with Surefire and Failsafe.
A Maven site, using the Docs Maven Skin, for sharing the project's documentation along the Javadocs and various reports which range from code quality to changes log.
Includes basic files such as readme, gitignore and license.

Sample project

A sample project shows what this Archetype is capable of creating.

Usage

It is a Maven Archetype, so it has to be included in the local repository, and then can be used to create a new project through command line or an IDE.

All the published versions are in the Maven repository, but installing the archetype into the local repository is always an option.

Installing

The archetype will be installed with the following Maven coordinates:

Group ID: com.bernardomg.maven.archetypes
Artifact ID: library-archetype
Version: (Check POM or badges)

To use it through command line type the following:

mvn archetype:generate -DarchetypeGroupId=com.bernardomg.maven.archetypes -DarchetypeArtifactId=library-archetype -DarchetypeVersion=[version]

If using an IDE check its documentation to find out how to use Maven Archetypes, and how to add these to the local repository.

Changing JDK Version

By default the project will be set for JDK 11. If this needs to be changed, for example to make use of JDK 17, the java.version property has to be overriden:

<properties>
   <java.version>17</java.version>
<\properties>

Documentation

Documentation is always generated for the latest release, kept in the 'master' branch:

The latest release documentation page.

Documentation is also generated from the latest snapshot, taken from the 'develop' branch:

The latest snapshot documentation page.

The documentation site is actually a Maven site, and its sources are included in the project. If required it can be generated by using the following Maven command:

mvn verify site

The verify phase is required, otherwise some of the reports won't be generated.

Running tests

The archetype plugin comes ready to run integration tests for the archetype by using the usual Maven command:

mvn verify

Check the archetype testing goal for more info.

If using Eclipse the tests may not run, due to an incompatibility with the Maven Invoker library. It is recommender running the tests through command line.

Collaborate

Any kind of help with the project will be well received, and there are two main ways to give such help:

Reporting errors and asking for extensions through the issues management
or forking the repository and extending the project

Issues management

Issues are managed at the GitHub project issues tracker, where any Github user may report bugs or ask for new features.

Getting the code

If you wish to fork or modify the code, visit the GitHub project page, where the latest versions are always kept. Check the 'master' branch for the latest release, and the 'develop' for the current, and stable, development version.

License

The project has been released under the MIT License.

library-maven-archetype's People

Contributors

Stargazers

Watchers

Forkers

mburgosh template-home millerjp

library-maven-archetype's Issues

Check if the extension used for uploading the docs can be set on the site plugin

On the site plugin page there is an example which sets the wagon extension on the site plugin:
https://maven.apache.org/plugins/maven-site-plugin/examples/adding-deploy-protocol.html

Check if this can be done, instead of using a global extension.

Put plugin configuration files together

Checkstyle, PMD and changes log files can be put together in a config folder. This way the number of folders in the project is reduced.

Add a "how to set dependencies" section to the usage page

The usage page for the new project is currently empty. It can be changed so that by default it shows how to get the library from Bintray.

Add information in the site about the pre-build validation

Add information about the checks done before building the project, such as the rules validation.

The maven-deploy-plugin plugin may work without the url param

The maven-deploy-plugin plugin has the deployment URL indicated as a URL parameter. This may be unnecessary, as the deployment plugin should be capable of acquiring the correct URL.

Check if the Maven releases plugin can be useful

Maven has a plugin for making releases. Check if it is actually useful.

Set the year automatically

The year of creation for the project, used as the POM inception year and the license year, is currently hardcored. Instead it should be set automatically as the current year.

The profile for publishing the docs is not easy to extend

Currently the URL for publishing the release docs is on the default profile, with an alternative one for development docs.

This is not good, as the default profile may be needed for other things than publishing docs.

For example, when creating a web service the default profile would be for the deployment version, using a real database, in contrast to the testing profile, which would use an in-memory database. The current profiles would collide with this.

It may be better changing the current default profile to a "release docs profile", and making use of it when deploying the docs.

Check if Coverity Scan can be added to the CI

Coverity Scan (https://scan.coverity.com/) creates reports from static code analysis. The main problem here is that there is a limit of how many times per week these reports may be generated.

Due to this, while it is interesting to add it to the CI procedure it should be controlled.

Not all the scripts are being copied

The .deploy.sh script is not being copied to the new project.

Configure new releases on Bintray automatically

The Bintray API (https://bintray.com/docs/api) allows synchronizing to Maven Central and adding files to the downloads list.

There must be a way to add these features to the deployment.

Changes report log and snapshots

When creating a new project if the version is a snapshot this part should be removed from the version in the changes log.

Add inception year to the new project POM

The POM on the project created through the Archetype should include the inception year.

Check if the Failsafe report can be generated automatically by the site plugin

Right not, it is needed to run the verify phase before the site (mvn verify site) to get the Failsafe reports. It would be better if these tests were run just as the Surefire ones, and shown along other reports on the site.

Move the Maven Eclipse plugin configuration to an Eclipse profile

The m2e plugin configuration is only needed for Eclipse, so it should not be part of the default configuration.

Move it to an Eclipse profile.

URL on the deployment plugin should point to the URL actually used

The URL for the deploy plugin should be set for the snapshots or releases repository, depending on the type of deployment. Right now it only points to one of them, and always to the same.

This may be done with a profile.

Allow skipping tests for deployment

The project is already tested by the CI service before deploying, so it should be possible skipping the tests so they are not run again for deploying artifacts.

A copy of the classpath is being used for the resources

The resources for the main project are being copied into a folders tree which copies the main classes class path.

These resources should be added to the root of the resources folder.

Check if Tattletale reports may be useful

JBoss Tattletale offer various code quality reports. They seem to be redundant with the ones already in use, but it can be interesting to at least check them.

Alternative Travis configurations

It may be a good idea adding a few alternative Travis files, in case for example only JDK 8 is supported.

Deployment scripts are not reusable

The deployment scripts make reference to the Travis branch variable, and to the pull variable. This should be changed so they can be used on othe CI services.

Prepare an archetypes repo

The releases would be more useful if they were stored ona an archetypes repo. One should be prepared for this.

Verify that the manifest is being created correctly

Maybe there is a plugin that can check this on the generated project?

Tests are not being skipped for development

It seems like the deployment profile is not working correctly, as it does not skip tests.

Create an example project

An example project, created from the latest release, should be created, and added to a Github repository.

This way it is possible to see what this archetype is capable of doing,

Is the dependencies info needed?

The dependencies info section, on the project information reports, tells how to configure the dependencies.

This should be linked on the usage section, or removed.

Make Bintray show the archetype correctly

Right now, trying to read the Bintray repo to find the archetype won't work. This has to be fixed.

Check if the deployment files are generated correctly

Most of the deployed files seem to be ok, but some, like the generated POM, should be checked to make sure they are correct.

.gitignore file is not copied

The .gitignore file is not copied on new projects using the archetype.

Seems to be a problem of the resources pluging. Changing from version 2.7 to 2.6 is supposed to solve it, but after trying it the bug persisted.

Add support for Codeship

Make the project easily usable on Codeship

Add a page talking about the technologies used in the project

It may be good that the documentation for new projects includes a page explaining the core technologies, libraries or frameworks used in the project.

Error with accents

The archetype seems to be ignoring the UTF8 encoding in some parts of it, as the accents are not copied correctly.

Add support for circleci

circleci is another popular CI service. Prepare the artifact so newly generated projects may run on it.

Add VersionEye report

It is possible getting a dependencies report at www.versioneye.com, the problem is that as this changes constantly the report should be read from that site.

Artifact id is not clear enough

The artifact id is currently "library", but it is not clear enough. It should be changed to "library-archetype".

Prepare a custom skin for the Maven site

Currently the Reflow skin is being used. It would be better to create a custom skin which I knew how to easily adapt to any project.

Check if the releases plugin is needed

The archetype includes the releases plugin. It would be better trying it a bit to check if it can actually be useful.

Default route for the development docs site

The readme, and probably other places, are appending "/development" to the development documentation URL. This should not be required, instead it should be set on the default URL.

Wrong links for development documents on readme

The links to the development documents on the readme for the new project is wrong. It's missing the "/development" folder on the route.

Use better environment variables

The current environment variables names are not too clear. Change them.

For example:
REPO_SITE_USER -> DEPLOY_DOCS_USER

Add support for deploying artifacts to Github

Currently the deployment scripts allow deploying the artifacts into a repository.

Another script should be created for depoying into Github releases.

Change source and target JDK variables

Currently the java.version.source and java.version.target variables are being used, but the defaults are maven.compiler.source and maven.compiler.target.

Add info about how to create a project from the archetype using commands

The documentation says that Eclipse should be used to build a project from the archetype. Add info about how to create it by using commands.

Unable to deploy

For some reason, the deployment to Bintray is failing with a '500, internal server error'.

Add a list of plugins being used

The documentation includes a list of reports being used, but not of the plugins. Add this.

Headers on the readme are dissappearing

In the project generated from the archetype the markdown headers are removed. It seems to be handling them like comments, and so they are ignored.

Links in the readme set as ftp and not http

The documentation links in the readme are set for the ftp protocol, not the http one.

Use a supressions filter for Checkstyle instead of a custom rules file

Currently the Checkstyle plugin is set to use a custom rules file, which does not include the noisy rules. Instead of this it may be better using a suppressions filter, which will hide these rules, while keeping the default rules list.

Deploy on tag, not on master

Maybe the artifact deployment should check if the code was pulled from a tag, not from the master branch.

This would allow reusing part of the scripts for other languages, and also would only try to do the final deployment when the user really wants to.

Check about changing the dependencyConvergence rule for the RequireUpperBoundDeps one

The dependencyConvergence and RequireUpperBoundDeps rules for the enforcer plugin does not seem to be compatible, but do a similar job.

The first ensures all the versions are the same, while the second ensures that the project makes use of a newer version.

This should be check, to find out which of the two options is best.