Update README.md to reference the GUI application.

[bdferris-v2]

Closes #1172.

I'm not sure how doc previews work in a PR, but you can also see the rendered updates (including the image) at:

https://github.com/bdferris-v2/gtfs-validator/tree/issue/1172/docs

[isabelle-dr]

This is becoming real!
For using the validator with the JAR file, we currently have the following:

1. on master, we provide instructions on how to download the latest JAR file from master using the GH Actions section (see this section) with a link to DOWNLOAD_SNAPSHOT_JAR.md.
2. To get the file from a specific release, in the top section of the README.md, the user gets a link to a branch where we replaced the flow described in 1. with the direct link (see the v3.0.0 branch).

I think this is not great because most users skip the top section and end-up getting the file from the GH Actions section, which is overkill for most users, and potentially not what we want since master is not always stable. Additionally, we can easily forget to update these branches when we have a release (proof: we forgot to do this for the 3.0.1 release).

I think sending the users directly to the release page is much better, and we should replace the "Run the app via the command line" Setup section with the same flow.

This brings me to the question: do we want to keep a link to DOWNLOAD_SNAPSHOT_JAR.md in the instructions here, in case a user wants to use the latest version of the validator, or to test that a bug is fixed? I think we should provide it, but make sure this is not the flow casual users will take.
@barbeau, thoughts?

In any case, @bdferris-v2 we should create a DOWNLOAD_SNAPSHOT_APP.md document or modify the existing DOWNLOAD_SNAPSHOT_JAR.md to describe how to get it from the GH Actions.

[bdferris-v2]

I think I'd try to encourage most users to download an official release installer and/or jar. I acknowledge there may be some power users / developers who want to use the latest version at HEAD, but that should be the exception, not the rule. I could take a stab at updating the README to reflect that stance if everyone agrees?

[isabelle-dr]

I could take a stab at updating the README to reflect that stance if everyone agrees?

Okay, thank you 🙏

[bdferris-v2]

@isabelle-dr I took a stab at updating README.

I didn't yet update DOWNLOAD_SNAPSHOT_JAR.md because I had a follow-up question. In PR #1166, I introduced the package_installers.yml workflow to capture the package installer artifacts. I had split it out into its own workflow because I thought it might run less frequently than the existing test_pack_doc.yml workflow. In retrospect, that turned out not to be the case. As such, I'm wondering if I should combine the workflow back into test_pack_doc.yml. Asking because it might make the documentation in DOWNLOAD_SNAPSHOT_JAR.md more straightforward (only one workflow to reference).

All that said, I don't think the DOWNLOAD_SNAPSHOT_JAR.md update is on the critical path here. Especially given that it's deemphasized in README.md now, I think we could get this PR in support of the 3.1.0 and address that snapshot documentation in a follow-up. Thoughts?

[barbeau]

Asking because it might make the documentation in DOWNLOAD_SNAPSHOT_JAR.md more straightforward (only one workflow to reference).

IMHO the JAR snapshots should really be uploaded to the GitHub Maven repo so they show up under the "Packages" section of the repo (versus just uploaded as artifacts of an Action). They are much easier to find that way - it cuts down the number of steps needed in instructions from like 6 to 1.

We did this on the gtfs-realtime-validator:

• All packages - https://github.com/orgs/MobilityData/packages?repo_name=gtfs-realtime-validator
• Latest webapp that we reference in snapshot download instructions (we haven't gotten to the v1.0 release yet) - https://github.com/MobilityData/gtfs-realtime-validator/packages/1268975

I say all this because if we do the above, then the documentation for the process to download the installer and the JAR snapshots will be different and we shouldn't combine them for now.

[isabelle-dr]

LGTM, thanks for the update @bdferris-v2. I just added a suggestion.
Let's address the following points in a follow-up:

• upload JAR snapshots to the GitHub Maven repo
• potentially combining test_pack_doc.yml and package_installers.yml

cc @maximearmstrong