Project

Profile

Help

Difficulty discovering "community site"

Added by E L almost 2 years ago

Nestled within the pages of the main web site for Saxonica, I discovered the plan.io "community site", which hosts the current forum.

However, the route to discovery is quite indirect. Meanwhile, both SourceForge and Github currently host variations of certain projects and information describing products. Pages on these sites are easily revealed through web searched, far more so than the active community site.

I hope it may be well received for me to offer a few suggestions:

  1. Represent the link more prominently on the main site to the community site.
  2. As SourceForge appears to be hosting both outdated browsable content and an unmaintained repository, retire them, or replace their main content with links to the sites and repositories in current use.
  3. Create repositories on Github that robotically mirror the development repositories, or create a single stub repository, hosting a readme document presenting a link to the community site.

Replies (18)

Please register to reply

RE: Difficulty discovering "community site" - Added by Martin Honnen almost 2 years ago

I can't speak for Saxonica but I don't think the Sourceforge zips/jars/files are outdated, they serve for downloading Saxon HE (in both the Java and the .NET variant). As for more prominent links to the online respository, the main documentation in https://www.saxonica.com/html/documentation11/about/index.html has a section "Source code, samples, and other resources" https://www.saxonica.com/html/documentation11/about/resources.html linking to SourceForge https://sourceforge.net/projects/saxon/files/Saxon-HE/ as the location for "The preprocessed source code, suitable for dropping into your IDE, is available as a download on SourceForge." while to https://saxonica.plan.io/projects/saxonmirrorhe/repository with the explanation "The original source code, including preprocessor directives, is available in a GIT repository. This also includes gradle build scripts, which you may need to customize to remove unwanted dependencies.".

Difficulty discovering "community site" - Added by Norm Tovey-Walsh almost 2 years ago

Thank you for the suggestion. This reminds me that I was hoping to
migrate from SourceForge to GitHub for the HE releases starting with
Saxon 12.

Be seeing you,
norm

--
Norm Tovey-Walsh
Saxonica

RE: Difficulty discovering "community site" - Added by Michael Kay almost 2 years ago

I think a lot of the problems with discovering Saxon information arise because there's too much information, not because there is too little. That's a harder problem to manage. What you are looking for is typically there, but not where you are looking.

My main concern with moving off SourceForge has always been that if we stop putting new releases there, people will just download the old releases (which we can't remove, for good reasons).

RE: Difficulty discovering "community site" - Added by E L almost 2 years ago

Michael Kay wrote in RE: Difficulty discovering "community site":

I think a lot of the problems with discovering Saxon information arise because there's too much information, not because there is too little. That's a harder problem to manage. What you are looking for is typically there, but not where you are looking.

Is it not the same general sense of too much information, and the right information being too hidden, as embodied by my original comments, leading to the suggestion of retiring those sites not designated for ongoing maintenance, adding any missing information to the active locations?

My main concern with moving off SourceForge has always been that if we stop putting new releases there, people will just download the old releases (which we can't remove, for good reasons).

I suppose the implication is that updated binaries are still uploaded to SorceForge. Why not simply host the binaries on the sites active for other uses, and replace the SorceForge site with a link to the active locations, or simply delete it?

RE: Difficulty discovering "community site" - Added by E L almost 2 years ago

Norm Tovey-Walsh wrote in Difficulty discovering "community site":

Thank you for the suggestion. This reminds me that I was hoping to
migrate from SourceForge to GitHub for the HE releases starting with
Saxon 12.

In such a case you would still have an awkward split between Github and planio. I recommend considering carefully the intended use of each site, and taking steps to facilitate a proper flow of traffic between them, to mediate their various purposes among the projects maintained by the organization. Ultimately, however, both sites serve the same general function, and support similar features. It is opaque to me why both would be used, other than perhaps to mediate the differences in usage for the commercial versus open sides of the projects.

RE: Difficulty discovering "community site" - Added by Michael Kay almost 2 years ago

You can't delete code that you've posted on SourceForge, as far as I'm aware.

RE: Difficulty discovering "community site" - Added by E L almost 2 years ago

Michael Kay wrote in RE: Difficulty discovering "community site":

You can't delete code that you've posted on SourceForge, as far as I'm aware.

Is there no way at all to be "forgotten", even by writing to the company and asking for an account to be deleted?

At any rate, you could still direct visitors to the new resources, in hopes of phasing out the SourceForge site, or at least making users aware that it in use for legacy. Even at the moment and old repository is appearing.

RE: Difficulty discovering "community site" - Added by Norm Tovey-Walsh almost 2 years ago

In such a case you would still have an awkward split between Github and planio. I
recommend considering carefully the intended use of each site, and taking steps to
facilitate a proper flow of traffic between them, to mediate their various purposes among
the projects maintained by the organization. Ultimately, however, both sites serve the
same general function, and support similar features. It is opaque to me why both would
be used, other than perhaps to mediate the differences in usage for the commercial versus
open sides of the projects.

All projects have history. I’m sure the SourceForge links go back a
couple of decades. The plan.io project predates GitHub, etc.

It’s a balancing act. Disrupting all of the build processes, user
expectations, historical artifacts, etc. just for consistency in a new
place (when we all know the new place is, ultimately, as transient as
the old places have turned out to be) isn’t an obviously good use of
time and energy.

OTOH, it makes sense to change with the times. Modern development is
focused on GitHub for the time being. There are some ways to integrate
github and plan.io more seamlessly. I’m experimenting with that for the
repository that’s hosting the machinery to build Python wheel release
for (what will be) SaxonC 12.0.

Be seeing you,
norm

--
Norm Tovey-Walsh
Saxonica

RE: Difficulty discovering "community site" - Added by E L almost 2 years ago

Norm Tovey-Walsh wrote in RE: Difficulty discovering "community site":

It’s a balancing act. Disrupting all of the build processes, user
expectations, historical artifacts, etc. just for consistency in a new
place (when we all know the new place is, ultimately, as transient as
the old places have turned out to be) isn’t an obviously good use of
time and energy.

OTOH, it makes sense to change with the times. Modern development is
focused on GitHub for the time being. There are some ways to integrate
github and plan.io more seamlessly. I’m experimenting with that for the
repository that’s hosting the machinery to build Python wheel release
for (what will be) SaxonC 12.0.

My interest has been trying to consider how new and casual visitors may find the resources needed without being encumbered or misled by abandoned ones, or ones used only for some of the active functions.

For those familiar with the project, such a concern is less personal, because they know how the different sites are used, and have been used.

Since it seems the history is richer than meets the eye, I will refrain from further specific suggestions, except to note that for those not actively contributing to the project, the most useful resources, in decreasing order of relevance, are static content, support forum, bug tracker, and code repository. If it is desirable that others in the future would have an easier experience than I have had, then I suggest that these core resources should be consolidated as much as possible into a common location, and that any redundant or outdated resources filing such roles should be deleted outright or replaced with redirection,

RE: Difficulty discovering "community site" - Added by E L almost 2 years ago

Norm Tovey-Walsh wrote in RE: Difficulty discovering "community site":

I’m experimenting with that for the
repository that’s hosting the machinery to build Python wheel release
for (what will be) SaxonC 12.0.

If you are able to share the progress, I would love to see it, even if just in an anonymous repo, such as a Github gist.

RE: Difficulty discovering "community site" - Added by Norm Tovey-Walsh almost 2 years ago

If you are able to share the progress, I would love to see it, even if just in an
anonymous repo, such as a Github gist.

It’s a public repo, https://github.com/Saxonica/BuildWheels

It’s a very odd repo though. The actual artifacts are built elsewhere
because we, for obvious reasons, don’t have a public repository for the
PE and EE code bases. This repo just uses a github action to download
the built libraries and run them through cibuildwheel.

On the plan.io side, I’ve set this up as a “mirrored” repository. That
is, there’s a plan.io github repo that mirrors the github one. That’s
not actually doing any useful work here, but I wanted to see how well it
works, in case we can leverage it in other ways.

Be seeing you,
norm

--
Norm Tovey-Walsh
Saxonica

RE: Difficulty discovering "community site" - Added by Norm Tovey-Walsh almost 2 years ago

My interest has been trying to consider how new and casual visitors
may find the resources needed without being encumbered or misled by
abandoned ones, or ones used only for some of the active functions.

I appreciate your comments. I think we can do better here, but it may
take a little while to get there.

Be seeing you,
norm

--
Norm Tovey-Walsh
Saxonica

RE: Difficulty discovering "community site" - Added by E L almost 2 years ago

Norm Tovey-Walsh wrote in RE: Difficulty discovering "community site":

I appreciate your comments. I think we can do better here, but it may
take a little while to get there.

As a start, I suggest maintaining at least mirrors of all public-facing repositories in GitHub, even if some are actively developed elsewhere, and adopting the location as the preferred one for public interaction. Having all in one place, on the well-known platform, makes interaction must easier for anyone to use the code.

RE: Difficulty discovering "community site" - Added by Norm Tovey-Walsh almost 2 years ago

As a start, I suggest maintaining at least mirrors of all public-facing repositories in
GitHub, even if some are actively developed elsewhere, and adopting the location as the
preferred one for public interaction. Having all in one place, on the well-known platform,
makes interaction must easier for anyone to use the code.

I think that’s a good suggestion. But I think, in fact, that I’ve
screwed up a little bit here and made things more confusing and less
useful. Apologies for that.

  1. Saxon HE has been open source for a couple of decades. We have
    historically distributed the source code in a zip file (on SF.net)
    that you can download and build.
  2. We have commercial customers who pay for access to bug fixes “live”
    (or nearly live) and we have a repository for that purpose.
  3. When I converted that system from Subversion to Git, I also created
    an “HE” version of the “live” system and made that repository public.

I thought step 3 was a good idea. We never advertised it because I never
actually finished testing that the build system worked with the HE only
sources.

You’ve found the repository (it was public, why wouldn’t you?) and it’s
become clear that my failure to adequately test the HE mirror repository
has contributed to some confusion and frustration.

I’m tempted to set that repository back to private for the moment, to
avoid leaving a public repository in a broken state.

I think you’re absolutely right that it would be good to have a public
repository, probably on GitHub, with good documentation and a clean
build process. I’m not sure how and when we will find time to make that
a reality as it clearly involves more work than I anticipated and we
have to balance those requirements against other tasks and obligations.

Be seeing you,
norm

--
Norm Tovey-Walsh
Saxonica

RE: Difficulty discovering "community site" - Added by E L almost 2 years ago

Norm Tovey-Walsh wrote in RE: Difficulty discovering "community site":

I’m tempted to set that repository back to private for the moment, to avoid leaving a public repository in a broken state.

Well, as you suggest, or perhaps some explanation in the documentation included at the top level would be reasonable.

I think you’re absolutely right that it would be good to have a public repository, probably on GitHub,

Yes. If you are using the other system for development and integration with the issue tracker, then you might simply keep the repositories in it private, and add hooks or some other robotic process for mirroring. The public would be happy to see all the code bases under GitHub, but I do recommend using the description field, or some other text area, to reference the site where you maintain forums and trackers.

with good documentation and a clean build process.

Yes, it would be great, especially if the tools would automate the dependencies resolution. If you post a comment here whenever you complete it, then I would receive the notification. The design of Gradle means the external environment generally has no requirements other than the build engine itself, or just the JDK.

RE: Difficulty discovering "community site" - Added by Norm Tovey-Walsh almost 2 years ago

Well, as you suggest, or perhaps some explanation in the documentation included at the
top level would be reasonable.

Right. Actually. I’ve discovered that there’s an EE dependency in the HE
build. That’s why it doesn’t work. So maybe this is closer to working
than I thought. It should be possible to remove that dependency.

With respect to your earlier question about setting the JDK version,
I was able to reproduce that. Near as I can tell, Gradle 6.7 doesn’t
work with JDK 17. Upgrading to a more recent version of Gradle is on my
list, but I haven’t got to it yet.

Be seeing you,
norm

--
Norm Tovey-Walsh
Saxonica

RE: Difficulty discovering "community site" - Added by Norm Tovey-Walsh almost 2 years ago

Yes, it would be great, especially if the tools would automate the
dependencies resolution. If you post a comment here whenever you
complete it, then I would receive the notification. The design of
Gradle means the external environment generally has no requirements
other than the build engine itself, or just the
JDK.

As of a few minutes ago,

./gradlew hejRelease

will successfully build a jar file, even with Java 17.

If you attempt to build PE or EE, you get a meaningful error message
instead of a few dozen Java compile errors.

I’m by no means finished in terms of documentation and cleaning up the
messages as you proposed. But it’s not actually, embarrassingly,
completely broken anymore.

Thank you for your patience.

Be seeing you,
norm

--
Norm Tovey-Walsh
Saxonica

RE: Difficulty discovering "community site" - Added by E L almost 2 years ago

I confirm building saxon-he-11.4.jar from the saxon11 branch, with JDK 17.

On the downside, the build operation now takes longer to complete.

Jokes aside, I'm glad about the receptivity for evolving toward more consistent application of best practices. I look forward to following the progress.

    (1-18/18)

    Please register to reply