Skip to content

Update README.md to reference the GUI application.#1173

Merged
bdferris-v2 merged 6 commits intoMobilityData:masterfrom
bdferris-v2:issue/1172/docs
May 31, 2022
Merged

Update README.md to reference the GUI application.#1173
bdferris-v2 merged 6 commits intoMobilityData:masterfrom
bdferris-v2:issue/1172/docs

Conversation

@bdferris-v2
Copy link
Copy Markdown
Collaborator

@bdferris-v2 bdferris-v2 commented May 26, 2022

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

@bdferris-v2 bdferris-v2 requested a review from isabelle-dr May 26, 2022 21:37
isabelle-dr
isabelle-dr reviewed May 27, 2022
View reviewed changes
Copy link
Copy Markdown
Contributor

@isabelle-dr isabelle-dr left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Copy Markdown
Collaborator Author

bdferris-v2 commented May 27, 2022

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
Copy link
Copy Markdown
Contributor

isabelle-dr commented May 27, 2022

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

Okay, thank you 🙏

@bdferris-v2
Copy link
Copy Markdown
Collaborator Author

bdferris-v2 commented May 27, 2022

@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
Copy link
Copy Markdown
Member

barbeau commented May 27, 2022

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:

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
isabelle-dr approved these changes May 31, 2022
View reviewed changes
Copy link
Copy Markdown
Contributor

@isabelle-dr isabelle-dr left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@bdferris-v2 bdferris-v2 merged commit 41ff596 into MobilityData:master May 31, 2022
@bdferris-v2 bdferris-v2 deleted the issue/1172/docs branch May 31, 2022 17:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@isabelle-dr isabelle-dr isabelle-dr approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Update validator instructions for the 3.1.0 release

4 participants

@bdferris-v2 @isabelle-dr @barbeau @maximearmstrong