Bilka wrote: ↑Thu Apr 11, 2019 7:34 am
As a sidenote, some of the errors have already been improved a bit. I changed the "no colon after category error" to instead say "category line does not end in colon", because that is what it is actually checking - a space after the colon will throw this error. The "duplicate date" error now says "duplicate date or version" and the basically empty "error on line x" now says what it expects the line to start with.
Just noticed another new error message:
Code: Select all
invalid changelog file, error on line 1, line does not start with exactly ' - ' or exactly ' '
Thanks for implementing it, that should be very helpful!
For the sake of an example, I'll document a complete debug session for a very basic changelog file. Let's see if I can get it to work by following the error messages. That's what I will start with:
It shows this error:
Code: Select all
invalid changelog file, error on line 1, line does not start with exactly ' - ' or exactly ' '..
Not quite as expected, as an error on line 1 always means that the first changelog entry doesn't start with a
proper header line. But just relying on the error message, I'll correct that anyway:
The parser now reports:
Code: Select all
invalid changelog file, error on line 1, missing category.
Let's add one:
I still get the same error:
Code: Select all
invalid changelog file, error on line 1, line does not start with exactly ' - ' or exactly ' '
However, this line ends with a colon, so it should be regarded as an incorrect category line. The error message is misleading because category lines must be indented with only two spaces. With the current error message, we'd just end up in a vicious circle. Let's try again, this time with a correct category line:
Now it's better:
Code: Select all
invalid changelog file, error on line 1, missing version
I'll just move the version line up, and because it didn't work previously, I fiddle around a bit and end up with a correct Version line:
Code: Select all
Version: 0.0.1
Info:
-ported to 0.17
Doesn't help though, we're back where we started:
Code: Select all
invalid changelog file, error on line 1, line does not start with exactly ' - ' or exactly ' '..
In my assumed role as a mod author, I give up at this point.
Let's start all over again:
Now, let's assume I get a message like this:
Code: Select all
invalid changelog file, error on line 1, line is not a valid header line.
So I add a header line:
Code: Select all
--------------------------------------------------------------------------------------------------
v0.0.1
-ported to 0.17
I still get an error, because this header line contains only 98 dashes.
So, it would make sense to make the error message more explicit:
Code: Select all
invalid changelog file, error on line 1, line is not a valid header line (must only contain exactly 99 dashes)
I finally have figured out what's wrong, so the file now is:
Code: Select all
---------------------------------------------------------------------------------------------------
v0.0.1
-ported to 0.17
This time, the error message is actually helpful again:
Code: Select all
invalid changelog file, error on line 2, missing Version: line.
So I take the clue and correct line 2:
Code: Select all
---------------------------------------------------------------------------------------------------
Version: 0.0.1
-ported to 0.17
Now I get
Code: Select all
invalid changelog file, error on line 3, line does not start with exactly ' - ' or exactly ' '..
The missing category isn't mentioned yet, but let's just ignore that for now and fix the error:
Code: Select all
---------------------------------------------------------------------------------------------------
Version: 0.0.1
- ported to 0.17
Ah, here's the expected message:
Code: Select all
invalid changelog file, error on line 3, missing category
So we add a category:
Code: Select all
---------------------------------------------------------------------------------------------------
Version: 0.0.1
Info:
- ported to 0.17
There's still an error:
Code: Select all
invalid changelog file, error on line 3, line does not start with exactly ' - ' or exactly ' '..
This line is supposed to be a Category line, however, because it ends with a colon. But the patterns suggested by the current error message are not correct in this case. Something like
Code: Select all
invalid changelog file, error on line 3, line does not start with exactly ' ' or exactly ' - ' or exactly ' '.
would be better. We could then proceed with
Code: Select all
---------------------------------------------------------------------------------------------------
Version: 0.0.1
Info:
- ported to 0.17
and the changelog would be parsed without an error.
Summary:
An error on line 1 should always result in
Code: Select all
invalid changelog file, error on line 1, line is not a valid header line (must only contain 99 dashes)
An error message for lines after the Version line should also include the 2-space indention for Category lines:
Code: Select all
invalid changelog file, error on line x, line does not start with exactly ' ' (Category: )or ' - ' or exactly ' ' (list of entries below a category)
I've not enough time now for more testing with more entries, but the suggested changes should improve your changes to the error messages even further!
Edit: Had to tag the error messages as code because a series of spaces is reduced to one space otherwise. If only there was a tag that would allow inline code (prints everything between start and end tag as is, preserving multiple spaces, but doesn't add an extra box like the code tag) in a post!