Roadmap

[Xymph]

Don't know if this is a common approach, but a discussion ticket seems a suitable way to talk about short-term plans for Wikimate updates.

I would like to wrap up #102 asap and move forward, as work on four new PRs is already done and tested. They are, in order:

1. issue Allow custom user agent #103
2. add table of contents to USAGE doc (Group sections and add table of contents in USAGE.md #108)
3. change API calls from PHP format to JSON (Change API requests from deprecated PHP format to JSON format #111)
4. issue Add support for passing maxlag to the API #92

Regarding 3: PHP format is deprecated and only maintained for now due to its popularity. New users should stick to JSON, and some API calls like opensearch don't even support PHP format.

The other reason to switch to JSON is that my implementation for 4. moves all API requests into a single request() method, which can then also contain the decoding step (and debug logging of request and response) in one central place, instead of the current multiple unserialize-s in methods like query(), edit() and upload(). And such centralizing can only be done if all requests use the same JSON format, as it is the only one supported by all API calls.

A format switch would ideally be verified with unit testing of those Wikimate methods, but this is an area I have little experience in, and it would be time-consuming to set this up. My own application scripts continue to work fine with the changes in 3. and 4. though.

The easy way (also avoiding potential merging conflicts) is to implement these PRs in the repo in the above order, so I'd prefer to just create and merge one branch at a time (although 1-2 can be done in parallel with 3-4). But that brings me back to the (slow) progress of #102, and @waldyrious 's availability here. While having a sparring partner is helpful, I certainly don't want to you as a punching bag my friend, and my afterthought commits in #102 demonstrate that reviews/feedback on my stuff is no luxury. 😉 Still, I would prefer not to stay stalled for long(er) times either.

Please share any thoughts on the above.

As for the longer term, I intend to look into existing issues again, and possibly explore coverage of more API features, but have no definite ideas/plans yet.

[Xymph]

I just ran phpdoc on Wikimate.php for the first time, and it pointed out some missing summaries, mostly for properties. So another planned PR (#109) is to add the absent info.

[waldyrious]

Don't know if this is a common approach, but a discussion ticket seems a suitable way to talk about short-term plans for Wikimate updates.

Yeah, I agree that roadmap issues like this sound like a great way to plan out work.

As for the changes themselves and their proposed implementation schedule, they sound sensible. I don't have any objections to what you've laid out.

Finally, regarding the feedback cycle and development pace of the repo: believe I should be able to respond to issues/PRs in this repo in a few days (less than a week for sure) in the foreseeable future. I don't want to be a bottleneck on the repo, though, so if you see that your own availability or drive can't sustain my pace of feedback, I'd rather you go ahead and make changes by yourself, than have the project lose steam out of trying to stick to our proscribed review process (especially since my reviews will be superficial at best). That should be a guideline, not a blind rule.

[Xymph]

Thanks for your initial comments on my planned updates. And while this looks like a flurry of activity now, once they're done we'll be able to catch our breaths again 😄 and any following PRs will likely occur at the much slower pace from before.

[Xymph]

Well, 0.13.0 took a lot more polishing work than I expected last week, but some of that was residue of older work, and the release came out better in the end. Thanks for all your help, @waldyrious. 👍

FYI, I've updated "our" entry on MediaWiki's library list now, and earlier already updated Wikipedia's bot table (actually here). The only non-English wiki I found with such a table is the Turkish one, also updated.

[waldyrious]

Yay, it's finally out! I agree the extra time we spent on it paid off. 👍

Great call with updating the wiki pages as well.

Looking forward to the next changes!

[Xymph]

Two further ideas:

• support the exclusion standard where we currently score a red No
• post the PHPDoc (or maybe ApiGen) generated documentation tree somewhere publicly

[waldyrious]

post the PHPDoc (or maybe ApiGen) generated documentation tree somewhere publicly

I like this! Perhaps GitHub Pages would be a good place to host these docs.

[Xymph]

post the PHPDoc (or maybe ApiGen) generated documentation tree somewhere publicly

I like this! Perhaps GitHub Pages would be a good place to host these docs.

Yes, that was my first inclination too, but being unfamiliar with it, I'll need to read up on how to place/update content there in an as-automated-as-possible fashion.

[Xymph]

Better not to clutter this high-level topic with the details of one task, so I created #110. Maybe you could move your last post into that thread?

[waldyrious]

#111 got me thinking — normally, such a change would require a major version bump, since we're changing the tool's interface. However, we're still using a 0.x "development" version scheme, so that wouldn't apply in this case. Still, perhaps this change would be a good moment to mark 1.0 (unless you're planning further backward-incompatible changes). WDYT? Should we make the next version 1.0?

[Xymph]

#111 got me thinking — normally, such a change would require a major version bump, since we're changing the tool's interface. However, we're still using a 0.x "development" version scheme, so that wouldn't apply in this case. Still, perhaps this change would be a good moment to mark 1.0 (unless you're planning further backward-incompatible changes). WDYT? Should we make the next version 1.0?

If this were an API breaking change I'd have pointed it out and my client scripts wouldn't have continued to run unmodified. The Wikimate methods all continue to return associated array structures: the only thing changed by the PR is how those were requested from the API and decoded. PHP+unserialize == JSON+json_decode(associated=true).

So no, the next release can simply be 0.14.0. When the 1.0.0 release would be appropriate I don't know yet - perhaps when Wikimate covers most of the API, but I doubt it'll ever get expanded that far.