[pom] Site still did not release, add scm data to allow it to occur

[hazendaz]

actual issue is all the overrides on release that are not needed. Fall to scm as that is the standard way maven suggests now even though release wants site. Reduced version of what I use in hazendaz/base-parent just enough to get it to go. The release still won't do it but left instructions on here to do this on demand. Takes maybe minute or two. Site is now updated which is an improvement. This alone below will do nothing without running the commands listed.

[ctubbsii]

This method of publishing is overly complex for my tastes, and there are a few things that I think are outright wrong with it.

I have set up the GitHub plugin for publishing to gh-pages in the parent POM. After a release tag is made, all you have to do is check out the tag and run mvn site-deploy without any of these changes. The only requirement is that you set up your GitHub credentials in your ~/.m2/settings.xml file using an OAuth token. This is my preferred method of publishing the sites to code.revelc.net, and what I've standardized in the parent POM.

See https://github.com/github/maven-plugins?tab=readme-ov-file#site-plugin

The site lifecycle will execute site:site to build the site and publish it in the target/site. I have the GitHub site plugin bound to the site-deploy phase of the site lifecycle, so it works as expected according to the Maven conventions using the pre-defined site lifecycle.

However, this PR changes the way I've set it up so that site deployment is done outside the site lifecycle, manually through direct use of specific plugins on the command line. It also adds some additional unnecessary steps. The site goal is the done the same (will run site:site), but then there's an unnecessary staging step that merely copies target/site to target/staging by calling site:stage which could be skipped if the scmpublish plugin was configured to use target/site instead of the default target/staging. Then, you have to call the scmpublish plugin to directly publish to the URL in the distributionManagement section. So, now you need configuration for that plus your credentials (setting up the credentials is similar, at least, but I'm not sure if this scmplugin will use ssh-agent correctly so I can keep the passphrases to my ssh keys secure... last I checked it didn't). This gets additionally confusing because the scmpublish plugin reuses this section which is set up for maven-site-plugin (the URL is read by maven-site-plugin:stage-deploy). But, it uses the scm: prefix so maven-site-plugin doesn't understand the <url>. So, this way of doing things is kind of a mix of conventions established by maven-site-plugin and conflicting conventions established by the scmpublish plugin. Plus, this way of doing things doesn't account for the GitHub-specific publish thing of adding the .nojekyll file in the gh-pages branch that is required to bypass the GitHub jekyll build, which is slow and unnecessary, and could cause compatibility problems with the static site generation done by maven-site-plugin.

If we really want to use the scmpublish plugin instead of GitHub's own, I'd be okay with switching over, but it needs to be done very differently than what this PR is doing in order to get everything working smoothly. Personally, I'd just prefer to keep things the way they are set up using GitHub's own plugin, which just works. If we were to switch, these things would need to be done first:

1. Don't use the distributionManagement section that maven-site-plugin expects to be able to use. Instead, configure the scmpublish plugin url directly using that plugin's own configuration instead of reusing the configuration intended for use with maven-site-plugin.
2. Specify the source directory directly in the plugin configuration, rather than add the wasteful step of copying target/site to target/staging.
3. Add an extra step to the site build to create the .nojekyll file
4. Bind it to the site-deploy phase of the site lifecycle, so that one can follow the normal build conventions instead of running things manually.

Again, personally, I think it's better to leave things as they are, though, using the method I set up in the parent POM.

To set it up, all you have to do is add an OAuth token in your ~/.m2/settings.xml file. You can go to https://github.com/settings/tokens to create the token (mine grants "read:org, repo, user:email") and set up your token using the <id>github</id>, like:

<servers>
  <server>
    <id>github</id>
    <password>{your encrypted OAuth2 token here}</password>
  </server>
 </servers>

[ctubbsii]

So, I'm going to revert these changes for now. If we want to set it up differently in the parent POM, we can do that. Otherwise, I suggest manually running the scmpublish plugin on the command line, if you prefer to do it that way, but pass all of its configuration options on the command-line also, instead of altering the POM. Having two different methods baked into the POMs to do the same thing leaves everything very confusing. And, you can still use your preferred approach without altering the POM at all.

Another alternative is to just run mvn site:site, checkout the gh-pages branch, and manually move over the target/site directory. It's slightly more tedious, but still pretty easy to do without making any changes to the POM that conflict with the parent POM's way of publishing the site.

[hazendaz]

Feel free to do as you please here. I simply followed exactly what maven has moved to doing over last 2 years.

[ctubbsii]

I don't want to make it harder for you to do the site deploys when you need to, though. So, while I'd like to scrub this for now, I'd like to revisit this and see if we can come up with something better... something more intuitive and easier for both of us to use (and anybody else, too, if they come along and volunteer to help).