docs: substrait_Spark Java library tutorial

[mbwhite]

Hello - this is a tutorial and description of how the Substrait-Spark java library can be used.

Would welcome comments - there is code that backs this up - but I wasn't sure where this would best to go. Would welcome feedback in that area.

[github-actions]

ACTION NEEDED

Substrait follows the Conventional Commits
specification for
release automation.

The PR title and description are used as the merge commit message. Please update your PR title and description to match the specification.

[mbwhite]

To the reviewers.... I've added the code - but it feels a little out of place in the structure of the repo; please do suggest where it would be better to put this code. Happy to oblige.

[EpsilonPrime]

Putting Java here in Substrait core feels really out of place. Is the reason you chose this location was to get the tutorial onto the Substrait website? Normally I would just write a tutorial.md near the code.

[mbwhite]

Hello @EpsilonPrime; every project has its preferences on how and where tutorial information is presented.
My question is really - I have this tutorial and the accompanying code to contribute; where would the project prefer it go?

[jacques-n]

I say put the doc on the website and put the Java code in the Java repo. Both should link to the other.

[mbwhite]

Hi @jacques-n did you mean put the doc onto the website and the code into the substrait-java repo?

The page in the main site documentation could just be a summary that could be extended.

One idea to throw-onto-the-table - for a Hyperledger Fabric project - I was one of the maintainers of the examples repo - its was a dedicated repo for examples/tutorials. Just code and markdown. but seemed to work well, plus it was able to have it's own build process to make sure the code still ran!

[jacques-n]

did you mean put the doc onto the website and the code into the substrait-java repo?

Yes.

examples repo ...

I thought about that. I felt like it would be more helpful to have local to each language binding.

it's own build process...

I would suggest where possible we include github workflows to test examples in each repo. Agree that otherwise they will stop working as code changes.

[mbwhite]

Thanks @jacques-n - I'll create PRs along those lines for both repos.

For the substrait-java have started a PR at substrait-io/substrait-java#293

Will close this one and re-open a new one for a reference to this example