Ensure creation of a valid update site

[ctubbsii]

See revelc/formatter-maven-plugin#177

[pit3k]

So currently, I'm unable to install this plugin in Eclipse until the update site is created, right?

[ctubbsii]

@pit3k I believe that's correct, but honestly, I'm not sure how this is supposed to work. I think @velo did most of the work on this, and I haven't had time to figure it out yet.

I think it should go something like this:

• The formatter-maven-plugin contains metadata which is picked up by m2e when a project is imported into Eclipse.
• That metadata points to information about this configurator, including an "update site" location from which to download the released configurator.

If this is roughly correct, then it means we need to ensure at least 2 things happen:

1. We need to make sure that formatter-maven-plugin contains the appropriate metadata
2. We need to create the update site and publish the configurator there (this may be possible by publishing to Maven Central, but if not, we may have to publish to somewhere at code.revelc.net)

[hazendaz]

@pit3k You can download the zip from maven central and install it using the zip itself in eclipse rather than an update site. That does work currently.

[ctubbsii]

If anybody can link to appropriate documentation for an Eclipse update site, I could probably create some static pages in a gh-pages branch which functions as a suitable update site, especially if we can continue hosting the artifacts themselves in Maven Central.

[pit3k]

@ctubbsii I believe it is supposed to work slightly differently.

1. You add formatter-maven-plugin to your project pom.xml. This causes the formatting to be validated whenever the project is built using maven. This entry in pom nor the plugin itself does not need to know anything about m2e or eclipse or update sites.
2. In your Eclipse IDE you install formatter-m2e-configurator. Whenever it sees a maven project managed by m2e that contains the formatter-maven-plugin, it reads its configuration and configures eclipse project-specific settings so that it uses the same formatting.

So, how you install the plugin in eclipse is up to the user and not metadata-driven. In particular, we use an oomph installer to provision it, and that is why having an http-enabled p2 update site is highly desired @hazendaz. Not sure if it's possible to download zip file from maven repo, unpack it and use such dir as local update site during oomph provisioning.

BTW, there is a very similar setup used by the checkstyle-maven-plugin + m2e-code-quality eclipse plugin (the later reads the maven configuration of the former from pom.xml and adjusts eclipse settings). In fact, the m2e-code-quality plugin supports more plugins than just checkstyle-maven-plugin, so maybe a good idea would be to add support for it to understand formatter-maven-plugin configuration as well, instead of maintaining a seaprate formatter-m2e-configurator?

[pit3k]

As far as creating the update site people often use maven site plugin to expose it via github.io. For example, m2e-code-qualifty uses this maven module:

• https://github.com/m2e-code-quality/m2e-code-quality/tree/develop/com.basistech.m2e.code.quality.site

in order to expose the update site under:

• http://m2e-code-quality.github.io/m2e-code-quality/site/

[ctubbsii]

@pit3k Right, you've described the manual installation method. What I was trying to describe is that m2e has the ability to automatically identify and install plugins. I've seen this in action with the buildhelper plugin. The Maven plugin somehow informed m2e that there was a companion m2e-configurator to add to Eclipse automatically. It may be the case that this only works if you've already added the update site to Eclipse. Either way, I think we need to figure out how to get the formatter-maven-plugin to give the hint to m2e that there's a companion m2e-configurator out there.

As for the update site, I think it's useful to look at what's generated:
https://github.com/m2e-code-quality/m2e-code-quality/tree/gh-pages/site

That shows that the jars themselves are stored in the gh-pages branch in GitHub. I don't think we should be storing the jar files in GitHub branches. That's messy. However, if we can generate such a site, but whose metadata points to the jars in Maven Central, that'd be ideal. Looking at this site.xml file, it looks like it might be possible, by specifying fully-qualified absolute URLs to the jar locations in Maven Central instead of relative ones within the site itself.

[hazendaz]

I sort of like the idea that we figure out how we can do away with this. The reality is there doesn't seem to be very many stand alone m2e integrations to start with and I keep seeing that it hasn't been required in some time. I sort of like the idea of it going to the m2e-code-quality if that is an option that works. I do like that we have a ton of info now so thanks @pit3k and @ctubbsii

[kwin]

Another alternative is to host on bintray (https://blog.bintray.com/2014/03/11/hosting-your-eclipse-update-site-p2-on-bintray-com/). That can also be automated quite nicely (look at https://github.com/kwin/cppcheclipse/blob/master/com.googlecode.cppcheclipse.parent/release.txt for some details)

[ctubbsii]

Another alternative is to host on bintray (https://blog.bintray.com/2014/03/11/hosting-your-eclipse-update-site-p2-on-bintray-com/). That can also be automated quite nicely (look at https://github.com/kwin/cppcheclipse/blob/master/com.googlecode.cppcheclipse.parent/release.txt for some details)

I'd prefer a solution that doesn't require us to register with another service. I'd like any committer on this project to, at least in theory, be able to easily publish and maintain it here. So, if we can publish using GitHub Actions, publish using a site-deploy Maven goal, or some other similar solution, I would prefer that.

[kwin]

You can publish via Github action to bintray with credentials stored as repository secrets (https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets), so only one technical account is necessary for everyone with according rights to trigger the Github action.

Github Packages unfortunately don't support p2 repos yet (https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem)

[ctubbsii]

I'd rather not sign up for bintray at all. I don't want any extra credentials to maintain or additional services to rely on. Can't we publish artifacts to an m2 repository that looks like a p2 repo? I think that's what the older version of this plugin originally tried to do in Maven central.

Or, we can just use the GitHub Pages site.

[kwin]

I don't think we should be storing the jar files in GitHub branches. That's messy.
(#1 (comment))

Or, we can just use the GitHub Pages site.
(#1 (comment))

Hard to see the direction here...
I was just making suggestions. Feel free to consider or disregard.

[ctubbsii]

Hard to see the direction here...
I was just making suggestions. Feel free to consider or disregard.

I do appreciate your sugestions, @kwin .

I don't mean to be self-contradictory. It's been 3 years since my earlier comment, but I think the idea was:

1. Put the p2 site in code.revelc.net (via gh-pages)
2. Have the p2 site metadata (xml) point to jars stored in Maven Central, since we're publishing there anyway

This seemed possible at the time, because it looked like p2 sites contained XML that had URLs in them, rather than relying on the directory layout, as m2 repositories do. I'm not an expert in this, though. It was just an idea. If we have to settle for having the whole site in gh-pages, I can accept that.

From what I can tell, you have a better understanding of how to make all this happen than I do, so I'm happy to support you making it happen, if you want to work on it. Ultimately, this action didn't stall because of lack of direction... it stalled because of lack of expertise and lack of time to do the legwork. I'm happy to support somebody picking it back up, through discussion of strategy on these issues, and reviewing any pull requests.

Also, I'm 'ctubbsii' at the-asf.slack.com, apache.org, and gmail.com, if you want to reach out to me directly on any of those. I'm happy to have a video or voice call to further discuss strategy forward here.

[hazendaz]

This could benefit a few other plugins I support where its the same issue. Lack of understanding on what all is needed and many of the things @ctubbsii noted. I've gotten away without providing that support on other plugins because there have been separate projects that happened to pick up the slack (thinking spotbugs-maven-plugin and some other project offers m2e integration).

[wetneb]

One approach that could be imitated here is what m2e-code-quality does: publishing the p2 site as a GitHub Pages site in the same repository. They have a script which gets called from a GitHub Actions workflow to regenerate the site when a new release is published.

[hazendaz]

I think we still really lack the how to do this properly. It had also been 7 years since this was released and the entire project was broken into pieces for the formatter plugin over that time. I got this fully updated to the latest Eclipse and was looking at the original approach of using maven central. Sonatype has changed a lot over this time too. I was able to successfully publish a 2.6.4 that includes all changes over the last 7 years. I've updated the readme for now to direct how to install this. I know its not the right way but it does work. If anyone can help try to get this working better that would be great! Some of the work I had to do I leveraged m2e-code-quality in folder layout and such so I do agree that is a good place to look. The project is using the latest tycho parent now as well. Sonatype was very picky against this project and I had to keep many lifecycles tycho wants off turned on to get it to properly go there. I suspect most of that can go away.

For anyone wanting to use this please give it a try to see if it works out as expected even in this current form. While I didn't show pictures on the readme I did capture each step to install it and it does require downloading from central first as it didn't seem to like trying to use it directly from here.