[jira] [Comment Edited] (MSITE-948) Site stage/deploy should respect 'child.site.url.inherit.append.path="false"' and not use relativePath related to that parent

["Jeremy Landis (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/MSITE-948?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17712060#comment-17712060 ] 

Jeremy Landis edited comment on MSITE-948 at 12/8/23 3:50 AM:
--------------------------------------------------------------

Discovered a work around which was not very clear and maybe right answer is to just make this more clear in FAQ.  While site isn't coded to handle the child inherit flags directly and fact that it doesn't make much sense when configured using git as site location, there was a work around hidden in plain site.  Think other tickets will need to get linked in here as many relate to same issue and could help others resolve.  I can look into finding all of them and linking.

While debugging and knowing this calculation comes about in 'getTopLevelProject(MavenProject)' or 'getDeployModuleDirectory' and while looking at the site pages documentation, realized the following...

 
|{{[<topSiteURL>|https://maven.apache.org/plugins/maven-site-plugin/stage-mojo.html#topSiteURL]}}|{{String}}|{{3.3}}|Top distribution management site url, for manual configuration when auto-calculated value doesn't match expectations. Relative module directory will be calculated from this url.
{*}User property is{*}: {{{}topSiteURL{}}}.|

 

To me and probably others that is not very clear at all.  Especially when what happens seems like a bug and at least some sort of flag to disable such as the long provided child url inherit flags.  The naming doesn't exactly scream out site url directly and is unnecessary long winded way of a boolean.  At any rate, setting that to '<topSiteURL>${project.distributionManagement.site.url}</topSiteURL>' in addition to the inherit child set to false in the parent ensures it can work as-is.  I do want to confirm if the inherit child even needs set but presume it must as it could just set top site oddly otherwise but at the moment, I was able to clear the ../repo.git related occurrence locally and scm publish worked correctly.  I'm pretty sure that further fixes site plugin usage directly without need for scm publish.  For multi module it further needs inherit set back to true in downstream projects so the site can get all staging.  Staging at least in context of running needs to pull it all together so this complicates the release plugin a bit in that I believe need goals to run as: deploy site site:stage site:deploy.  A 'site-stage' would be nice to clean that up a bit when scm publish is being used along with maybe a flag for that instead of defining <goals>.

I want to do a bit more testing in automated fashion to make sure things work out with release plugin involved.  I'll still look to getting a small reproducible together as I kind of feel like some improvements can be made to this.  Knowing how difficult this has been, seeing many tickets through the years on similar related issues, knowing others in OSS have same struggles with site, etc.  But bottom line for now, think there was enough here to fully figure this out.  I may end up using 'mybatis' to actually demo this entire thing out more publicly as we are using a very old plugin to pull off site and not maven directly due to issues over the years but that uses jsch and is starting to show issues on mac.  And its in probably best position to show this overall.

As long as I can continue to add links to help others out here and continue posting as needed, feel free to just close out the ticket as it stands.  Part of me opening this was clearly what was needed to at least cause me to figure it out.  Sorry to be a bother here and hoping this at a minimum helps others out with site usage.


was (Author: hazendaz):
Discovered a work around which was not very clear and maybe right answer is to just make this more clear in FAQ.  While site isn't coded to handle the child inherit flags directly and fact that it doesn't make much sense when configured using git as site location, there was a work around hidden in plain site.  Think other tickets will need to get linked in here as many relate to same issue and could help others resolve.  I can look into finding all of them and linking.

While debugging and knowing this calculation comes about in 'getTopLevelProject(MavenProject)' or 'getDeployModuleDirectory' and while looking at the site pages documentation, realized the following...

 
|{{[<topSiteURL>|https://maven.apache.org/plugins/maven-site-plugin/stage-mojo.html#topSiteURL]}}|{{String}}|{{3.3}}|Top distribution management site url, for manual configuration when auto-calculated value doesn't match expectations. Relative module directory will be calculated from this url.
{*}User property is{*}: {{{}topSiteURL{}}}.|

 

To me and probably others that is not very clear at all.  Especially when what happens seems like a bug and at least some sort of flag to disable such as the long provided child url inherit flags.  The naming doesn't exactly scream out site url directly and is unnecessary long winded way of a boolean.  At any rate, setting that to '<topSiteURL>${project.distributionManagement.site.url}</topsiteURL>' in addition to the inherit child set to false in the parent ensures it can work as-is.  I do want to confirm if the inherit child even needs set but presume it must as it could just set top site oddly otherwise but at the moment, I was able to clear the ../repo.git related occurrence locally and scm publish worked correctly.  I'm pretty sure that further fixes site plugin usage directly without need for scm publish.  For multi module it further needs inherit set back to true in downstream projects so the site can get all staging.  Staging at least in context of running needs to pull it all together so this complicates the release plugin a bit in that I believe need goals to run as: deploy site site:stage site:deploy.  A 'site-stage' would be nice to clean that up a bit when scm publish is being used along with maybe a flag for that instead of defining <goals>.

I want to do a bit more testing in automated fashion to make sure things work out with release plugin involved.  I'll still look to getting a small reproducible together as I kind of feel like some improvements can be made to this.  Knowing how difficult this has been, seeing many tickets through the years on similar related issues, knowing others in OSS have same struggles with site, etc.  But bottom line for now, think there was enough here to fully figure this out.  I may end up using 'mybatis' to actually demo this entire thing out more publicly as we are using a very old plugin to pull off site and not maven directly due to issues over the years but that uses jsch and is starting to show issues on mac.  And its in probably best position to show this overall.

As long as I can continue to add links to help others out here and continue posting as needed, feel free to just close out the ticket as it stands.  Part of me opening this was clearly what was needed to at least cause me to figure it out.  Sorry to be a bother here and hoping this at a minimum helps others out with site usage.

> Site stage/deploy should respect 'child.site.url.inherit.append.path="false"' and not use relativePath related to that parent
> -----------------------------------------------------------------------------------------------------------------------------
>
>                 Key: MSITE-948
>                 URL: https://issues.apache.org/jira/browse/MSITE-948
>             Project: Maven Site Plugin
>          Issue Type: Bug
>          Components: site:stage(-deploy)
>    Affects Versions: 3.12.1, 4.0.0-M7
>            Reporter: Jeremy Landis
>            Priority: Major
>
> All versions of maven have long been affected by this and there are many tickets opened / closed claiming to have resolved or seem to be outstanding for years with no resolution.  I believe they are mostly related.
> The 'child.site.url.inherit.append.path="false"' was added back in maven 3.6.0 with claim to stop this behaviour but its never worked outside of effective pom looks right IMO.  At least most platforms support that now (artifactory was late in that game).
> Currently regardless of that setting, the maven site plugin doesn't respect it or even look at it from what I can tell.  Its there in the debug tree but the code doesn't appear to look at that to determine what it will do with relativePath.
> So, if I have project example [https://github.com/hazendaz/base-parent] and I happen to have those set (such as [https://github.com/hazendaz/base-parent/commit/58e9f8a7749a80e74e8197d5b90b17458cadb161]), then anything downstream using that parent which is unrelated I would expect to adhere to the request and not attempt to use the super pom for its calculations at all.  But it does not do so.
> I suspect areas of code problematic are getTopLevelProject(MavenProject) or 'getDeployModuleDirectory'.  The later being where it matters with 'relativePath' determined.
> The main issue is with multi module downstream projects.  Fixing this issue I suspect would have immediate impact on being able to use the site plugin directly and not need scm publish.  Scm publish tends to work for single module but it still suffers from fact that the site plugin messes up the data before it ever gets there.
> For example, if my project is 'somerepo.git', I would expect site:stage to put the data in 'target/staging' as the documentation states it will do so.  It however does not, regardless of the above noted setting.  What it does instead is determine that it needs the relative path to be '../somerepo.git' just because it has a parent pom from some other project from same hosted platform (gh-pages on github).  So the staging then puts that in 'target/somerepo.git' instead.  So maven scm publish cannot even see that.  The site deploy fails to do it correctly as it completely changes out the repo to deploy to and tries to go to the parent which in most cases like this isn't related at all.  My base super pom for example is used by quite a number of repos and they all have issues with site distributions as a result.
> So how can we make the site plugin actually respect 'child.site.url.inherit.append.path="false"'?  Or any way to actually make that easier like configure it to just stop doing that logic as unnecessary.  The pom settings IMO are over bearing as it is so a config option would be far better and easier to implement.
> I've debugged this far enough to just keep changing the site plugins determination on the relativePath to be './' which fixes the issue.  Note: The rest of relative path for multi module is needed but starting part was wrong '../' vs './'.
> IMO I don't think maven should even be touching items like this, its so hard to understand the math as a result.  Thus why so many tickets get opened for same thing in various different ways.  Over the years we have tried just about everything to make this work and honestly the only thing that really does currently is to drop maven from doing the site distribution entirely and use gh-actions to do the same or other solutions on different platforms.  It would be better IMO to use maven site plugin directly and/or with scm publish if it consistently worked as documented.  Maybe a flag isn't even need, maybe just fixing maven site plugin to stop going outside of the staging folder would be a good step 1 as scm publish should be ok then.



--
This message was sent by Atlassian Jira
(v8.20.10#820010)