docs: Update RULES.md to include NOTICES.md information & delete NOTICES.md by isabelle-dr · Pull Request #1132 · MobilityData/gtfs-validator

isabelle-dr · 2022-05-03T23:37:03Z

Closes #1006
Closes #1154

Summary:
Following the discussions in PR #1127 (comment), the objective of this PR is to provide a better user experience when reading the validation report. This is part of the effort of the 3.1.0 release.
The HTML report in #1127 will link to the corresponding piece of documentation using the anchor links, in order to ease the process of (1) understanding what the issue is, and (2) fixing the dataset.

This PR contains the following changes:

the first part of RULES.md has been reworked to make it more useful for a regular user of the validator. The parts that are useful only when contributing have been moved to NEW_RULES.md, which describes how to add a new rule.
the information available in NOTICES.md has been added to RULES.md using a collapsable feature to make the file more digestible. The information added is:
- the notice_codes
- the notice fields description
- the affected files
added the notice code into the first table
some cleanup & small documentation fixes
NEW_RULES.md has been updated to reflect the change of documentation

Expected outcomes:

All the documentation that a user needs to understand the validation results & fix their dataset is available in RULES.md
The user doesn't need to guess the mapping between the CamelCase NoticeName and the snake_case notice_code

Please make sure these boxes are checked before submitting your pull request - thanks!

~~Run the unit tests with gradle test to make sure you didn't break anything~~
Format the title like "feat: [new feature short description]". Title must follow the Conventional Commit Specification(https://www.conventionalcommits.org/en/v1.0.0/).
Linked all relevant issues
Include screenshot(s) showing how this pull request works and fixes the issue(s)

NEW_RULES.md is used if someone wants to contribute to a new rule, and RULES.md is used to interpret the validation report

+ a lot of cleanup

isabelle-dr · 2022-05-04T11:50:21Z

@maximearmstrong this is ready for review! :)
Do you know why the tests didn't run on this PR?

maximearmstrong

Some suggestions for changes in-line before approval. Thank you for this @isabelle-dr!

docs/NEW_RULES.md

RULES.md

Co-authored-by: Maxime Armstrong <[email protected]>

…a/gtfs-validator into documentation-update

Co-authored-by: Maxime Armstrong <[email protected]>

CLAassistant · 2022-05-10T22:50:24Z

All committers have signed the CLA.

This reverts commit 2a03456.

This reverts commit c8f870e.

…c when missing

isabelle-dr · 2022-05-17T16:54:50Z

I have applied the changes:

remove notice class to use only notice code
put the references to the spec outside of the dropdown & add the reference to the spec for notices that were only referring to the python validator
other small fixes & typos

@barbeau PTAL, the work is done on my end :)

barbeau

Thanks for all this work @isabelle-dr! I think it looks much better than before - much easier to read IMHO.

I found a few small typos in the below comments/suggestions.

docs/NEW_RULES.md

RULES.md

Co-authored-by: Sean Barbeau <[email protected]>

isabelle-dr · 2022-05-17T19:27:02Z

What an eye @barbeau! 🧐 Thank you

@maximearmstrong, could you have a last look & approve this PR if it all looks good?

RULES.md

barbeau

LGTM, thanks @isabelle-dr!

maximearmstrong

2 small things aside, LGTM! Thank you @isabelle-dr :)

Also, we had to reconfigure the CLA assistant last week and I think we will need your signature in order to merge.

RULES.md

Co-authored-by: Maxime Armstrong <[email protected]>

maximearmstrong · 2022-05-18T14:00:27Z

Thank you @isabelle-dr ! The other checks won't be performed because this PR only changes the .md files, so I'm merging it.

isabelle-dr added 3 commits May 3, 2022 14:55

Move code example from RULES.md to NEW_RULES.md

f887a41

NEW_RULES.md is used if someone wants to contribute to a new rule, and RULES.md is used to interpret the validation report

Add notice codes in RULES.md

a696622

Update RULES.md with info from NOTICES.md in collapsable

41e472f

+ a lot of cleanup

isabelle-dr mentioned this pull request May 3, 2022

Missing notice details for three validator rules #1133

Closed

6 tasks

Remove NOTICES.md and the references to it

6ca004c

isabelle-dr changed the title ~~Update RULES.md to include NOTICES.md information~~ Update RULES.md to include NOTICES.md information & delete the file May 3, 2022

isabelle-dr changed the title ~~Update RULES.md to include NOTICES.md information & delete the file~~ Update RULES.md to include NOTICES.md information & delete NOTICES.md May 3, 2022

isabelle-dr changed the title ~~Update RULES.md to include NOTICES.md information & delete NOTICES.md~~ Docs: Update RULES.md to include NOTICES.md information & delete NOTICES.md May 4, 2022

isabelle-dr changed the title ~~Docs: Update RULES.md to include NOTICES.md information & delete NOTICES.md~~ docs: Update RULES.md to include NOTICES.md information & delete NOTICES.md May 4, 2022

isabelle-dr added 2 commits May 3, 2022 20:11

Add mention about v2 to v3 mapping

4c2c241

Improve paragraph

c60d3cb

isabelle-dr requested a review from maximearmstrong May 4, 2022 11:39

fix collapse

47be067

isabelle-dr mentioned this pull request May 4, 2022

feat: Implements the HTML output MVP #1127

Merged

4 tasks

maximearmstrong marked this pull request as draft May 4, 2022 14:53

maximearmstrong marked this pull request as ready for review May 4, 2022 14:53

isabelle-dr mentioned this pull request May 4, 2022

feat: recommended file annotation #877 #1123

Closed

4 tasks

maximearmstrong suggested changes May 4, 2022

View reviewed changes

isabelle-dr and others added 11 commits May 4, 2022 18:04

Touch [acceptance test skip]

3622f78

Update docs/NEW_RULES.md

fe61c4d

Co-authored-by: Maxime Armstrong <[email protected]>

Update docs/NEW_RULES.md

feeb2bb

Co-authored-by: Maxime Armstrong <[email protected]>

Update NEW_RULES.md & move RELEASE.md

99159f7

Merge branch 'documentation-update' of https://github.com/MobilityDat…

55e713a

…a/gtfs-validator into documentation-update

fix typo in NEW_RULES.md

42ba917

Update RULES.md

80cb57e

Co-authored-by: Maxime Armstrong <[email protected]>

Update RULES.md

0d031a4

Co-authored-by: Maxime Armstrong <[email protected]>

Update RULES.md

de3c495

Co-authored-by: Maxime Armstrong <[email protected]>

Update RULES.md

c2a0e01

Co-authored-by: Maxime Armstrong <[email protected]>

Update RULES.md

e5dbf3a

Co-authored-by: Maxime Armstrong <[email protected]>

isabelle-dr added 3 commits May 16, 2022 15:20

Revert "Remove redundant anchor links"

df4b4c3

This reverts commit 2a03456.

Revert "test for anchor links"

e45626b

This reverts commit c8f870e.

replace class name by notice code in documentation

ad3ef0a

isabelle-dr mentioned this pull request May 17, 2022

Update references to the python validator in RULES.md #1154

Closed

isabelle-dr added 2 commits May 17, 2022 12:34

remove the references from details section & add reference to the spe…

1c5a000

…c when missing

small fixes

518492a

isabelle-dr added 5 commits May 17, 2022 12:56

solve merge conflicts

76819fa

solve merge conflicts

e0a5a79

solve merge conflicts

75e97f8

solve merge conflicts

766154f

Merge branch 'master' into documentation-update

898f83c

barbeau reviewed May 17, 2022

View reviewed changes

docs/NEW_RULES.md Outdated Show resolved Hide resolved

docs/NEW_RULES.md Outdated Show resolved Hide resolved

RULES.md Outdated Show resolved Hide resolved

RULES.md Outdated Show resolved Hide resolved

RULES.md Outdated Show resolved Hide resolved

RULES.md Outdated Show resolved Hide resolved

isabelle-dr and others added 6 commits May 17, 2022 15:24

Update docs/NEW_RULES.md

e20899b

Co-authored-by: Sean Barbeau <[email protected]>

Update RULES.md

5b38e77

Co-authored-by: Sean Barbeau <[email protected]>

Update RULES.md

f754338

Co-authored-by: Sean Barbeau <[email protected]>

Update RULES.md

5327ed4

Co-authored-by: Sean Barbeau <[email protected]>

Update RULES.md

9733145

Co-authored-by: Sean Barbeau <[email protected]>

Update docs/NEW_RULES.md

e5b59f1

Co-authored-by: Sean Barbeau <[email protected]>

barbeau reviewed May 17, 2022

View reviewed changes

RULES.md Outdated Show resolved Hide resolved

remove line

cd6cc63

barbeau approved these changes May 17, 2022

View reviewed changes

maximearmstrong approved these changes May 17, 2022

View reviewed changes

RULES.md Show resolved Hide resolved

RULES.md Outdated Show resolved Hide resolved

isabelle-dr and others added 2 commits May 18, 2022 09:09

Update RULES.md

5ac8067

Co-authored-by: Maxime Armstrong <[email protected]>

Update RULES.md

b658c85

Co-authored-by: Maxime Armstrong <[email protected]>

maximearmstrong merged commit 46c46f8 into master May 18, 2022

maximearmstrong deleted the documentation-update branch May 18, 2022 14:00

Conversation

isabelle-dr commented May 3, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

isabelle-dr commented May 4, 2022

Uh oh!

maximearmstrong left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CLAassistant commented May 10, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

isabelle-dr commented May 17, 2022

Uh oh!

barbeau left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

isabelle-dr commented May 17, 2022

Uh oh!

Uh oh!

barbeau left a comment

Choose a reason for hiding this comment

Uh oh!

maximearmstrong left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

maximearmstrong commented May 18, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

isabelle-dr commented May 3, 2022 •

edited

Loading

CLAassistant commented May 10, 2022 •

edited

Loading