#metabrainz

Which description?

MBS-12839: Allow searching for edits by kind of edit type

The description our template currently tries to find from the wiki (but AFAICT only exists for https://musicbrainz.org/doc/Edit_Types/314 because I added it last year to test)

Ok, I added https://tickets.metabrainz.org/browse/MBS-12840 and marked it as depending on yours

MBS-12840: Revert lumping of historic edits into reused names

It would probably be better to help with keeping this documentation synced but there is nothing we cannot do about the current documentation from the wiki atm.

Well, I think we have pretty much no docs, so I was thinking we could decide to use hardcoded docs first, then start actually writing some :D

We can also start on the wiki, but hardcoding from the start makes them translatable, which is nice I guess

Where are all the https://musicbrainz.org/doc/Edit_Types/* from?

Generated in Perl

Only the "Description" section is taken from the wiki

root/doc/edit_type.tt

aerozol: thanks for the ping. there appears to be a bug in LB related to YIM causing data for that user to go missing, i'll take a look.

reosarevok: I didn’t know about it. It is good that everyone can easily edit it from the wiki atm.

Is that a new feature? Or just undocumented?

I think it's undocumented

It's 12 years old :D

But I didn't even know about it

(until I started porting these to React)

Could have some input from the community about it.

I'd argue edit types should be documented by the team (when they are added or modified)

But dunno :)

Also, heh. Every edit's sidebar has

That's not even a link to the *appropriate* edit type page, just the generic list

Right, there is no validation for this kind of transclusion I guess?

Not unless you add the edit to the transclusion table, it's the same as with /doc

(I did that with the one I documented)

Guess I'll add a ticket to link to the specific edit type from the sidebar, that should be a trivial fix

reosarevok: I'm here now too, tell me when you've finished up with your thing

If there is no edit type using it, it might be safer to shut it down then.

I'll also enter a ticket then to move from wiki to code for descriptions

alastairp: as soon as I've entered the tickets I'm all yours

👍

Well, mostly.

To code or to the database.

Yeah. I'm thinking code for now because we don't have an edit type table

(Probably better to the code indeed, dunno)

But that's a bit puzzling, so eventually we might want to change that

We will have a schema change this year ;)

You literally told me you wanted no big changes :D

We'll see :) Something to talk at a team meeting too

It’s not big as it doesn’t affect replication.

(Or maybe it does but just by creating a new dispensable table.)

I mean, it would mean rewriting how we get and use edit data, I guess? Unless it's just kind of a copy of what's already in the code. But certainly doable

https://tickets.metabrainz.org/browse/MBS-12841 for the doc links

MBS-12841: Link to the specific edit type documentation from edits

And https://tickets.metabrainz.org/browse/MBS-12842 for the moving to code (or db)

MBS-12842: Move edit type descriptions from wiki to code

alastairp: Ready for you

reosarevok: so, I had started at this point: https://swagger.io/tools/open-source/

it all seems overly complex. there's the standard for specifying APIs. there's an open-source tool to take a specification and generate html

(reminder, ticket is https://tickets.metabrainz.org/browse/MBS-12169)

MBS-12169: Autogenerated/interactive API documentation

there's a commercial service called SwaggerHub, which I signed up for and immeidately got an email from a salesperson

however, https://editor.swagger.io/ looks pretty good as a free editor

so there's a yaml specification which includes things like "this is an endpoint", "these are the parameters", "this is the output"

and it seems like much of this could be autogenerated from a simpler doc, however I'm not sure if it could be autogenerated from musicbrainz-server code

Well, we do have a lot of tests at the very least which are literally "URL, expected response"

it looks like there's also a templating/reference syntax (in the editor example there's a bunch of `$ref: '#/components/schemas/Pet'`

reosarevok: Also added https://tickets.metabrainz.org/browse/MBS-12843 and link to the ticket you added. (Fin.)

MBS-12843: Allow searching for edits by entity type related edit type

so much of the MB api has bits which are shared betwen all entities, so this might be a way of reducing the size of the schema definition

mmd-schema does use reusable components FWIW

right

I haven't looked much into the way to show example output of queries

and of course, if we change the output then that should be updated too

Is this the kind of stuff where you can actually do a query and get the results? I like how https://cloud.memsource.com/web/docs/api#tag/Au... works

But I dunno if that's what we can get from this

yeah, swagger will do that. in the editor url see the "try it out" button

initially I was thinking of trying to manually put together a specification for get/browse/search for a single entity

just to see what it could look like

Sounds like a good plan

so I'm happy to play with that today, not sure where you could help, unless we try and do it in a collaborative editor

or perhaps you could look into what we can automate for extracting endpoints and parameters from the WS code

Well, each file has stuff lik

*like

Those are the options for area

So it's kinda there, but for example it doesn't have anything that specifically says the first of those is a search, second a collection browse, third a normal browse. Fourth being a lookup is listed at least

that definitely seems like it might be possible to inspect this and generate the structure. Although I guess it has no textual descriptions in it

would it make sense to add textual descriptions directly to the perl code?

What should the descriptions look like?

Stuff like " description: Update an existent pet in the store" in the example?

yeah, I guess so. Although now I just noticed that https://musicbrainz.org/doc/MusicBrainz_API doesn't even have documentation like that

it just says "You can perform a lookup of an entity when you have the MBID for that entity:", without ever naming an entity

(of course it lists the entities earlier on the page)

the four main musicbrainz entities https://usercontent.irccloud-cdn.com/file/gpGQy...

Then there's stuff like

In the validator page

Yes, I agree that pet is very much a basic thing for MB

does that mean AnimalBrainz is on the cards as well?

well, we already have a monkey

given that AB is being retired we could also reuse the acronym.

right. I've not got into parameter definitions in openapi yet, I wouldn't be surprised if it can properly handle it. but again it's a question of deciding if it's easier to auto-generate it from the code, or just carefully maintain the specification manually

I'm guessing the best option long term might be to have a yaml or json file with the definitions, then have code to make the required $ws_defs based on that

So have a specification, and use *that* to generate the code

But not sure if that'd work well

oh yeah

alastairp: lmk when you have a moment to talk about time zones.

Also, yes, I do know the API docs are mediocre

I was aiming for something kinda like this swagger thing but it's hard to do that decently on a wiki (I'm sure it could still be a lot better than what I ended up with, mind)

So do I understand correctly some of our APIs are already documented in Swagger? Where do they live?

I would like to take a quick look to what can be done

s/to/at/

(and to understand where we'd have the finished docs)

reosarevok: https://api.test.bookbrainz.org/1/docs/

Hmm

I like this, at least

lucifer: hi

Did you try to implement includes into this?

It is pretty neat

(I see BB does separate calls instead)

reosarevok: I'm reading the swagger docs for how to do ?inc now

alastairp: https://usercontent.irccloud-cdn.com/file/fNFCb...

> To describe the parameter contents, you can use either the schema or content keyword. They are mutually exclusive and used in different scenarios. In most cases, you would use schema. It lets you describe primitive values, as well as simple arrays and objects serialized into a string.

technically, its right but from the user perspective weird.

(see the timestamp of the 3rd, 4th, 5th listen)

lucifer: you'll have to explain to me why the 4th has a timestamp of 2pm

alastairp: because i submitted it in IST :), whereas the others in NZST.

and when listens are sorted by converting the times to utc, this is how it lines up.

can you please give me a list of the timestamps as submitted for all 5 of them?

my initial response to this is "if the timezone changes, then of course the data will be different"

but I'm not sure if I'm missing something

yeah the issue is because timezone changed, likely this won't happen in any sane cases. so garbage in garbage out i guess.

You could specify the timezone

On display

lucifer: OK, looking at the data I think I understand what's going on now

It can happen if I'm listening to music on a plane or something, and then change my timezone as soon as I land somewhere new, no?

That'd be a legitimate case

these are listened to all in order, a few minutes apart?

reosarevok: but unless your phone automatically changes the timezones during the journey, LB wouldn't know.

alastairp: yes

but most of them are "2023-01-18T21:55:19+13:00" and one is "2023-01-18T14:28:13+05:30"

but they are just a few minutes apart

lucifer: well, sure, but once I land I'm going to change it (or my phone will)

So there's still going to be a point where there's going to be a jump

yes makes sense

remind me, when we had this discussion last week, did we decide on which timezone to use when showing listens on the listen page?

the user who submitted the listens, their timezone.

but "their timezone" being the value that we store in the database as the offset, or the user preference, or the timezone reported by the browser?

because we could use the browser timezone, and then this wouldn't be a problem at all

all of that, in that same order of preference.