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.

[waldyrious]

Ah, I see. Yeah, I did get that impression from what you wrote in the PR description, but while reading the code diff, I didn't make the connection that "Unserialized php" = "Decoded JSON" and my brain snapped back into the assumption the output was the same content with a sightly different representation :)

As for 1.0, I get what you mean, but OTOH Semantic Versioning does recommend

If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you’re worrying a lot about backwards compatibility, you should probably already be 1.0.0.

At least two of those are true, for what that's worth. Releasing the first major version would also allow us to make our semantic versions more, well, semantic. But I definitely get the appeal of leaving 1.0 to when the coverage of the API is closer to complete. I'm OK with whatever you prefer.

[Xymph]

As for 1.0, I get what you mean, but OTOH Semantic Versioning does recommend

Thanks for digging that up. Yes, I agree we're sufficiently out of development to go for 1.0. But it seems fitting to have the public API documentation site online when we do that. Also, I noticed that a Logout call exists which is easy to implement, so it would be a cleaner 1.0 if it supports both login and logout. However little used the latter may be, since one is effectively also logged out once the client script completes. I never missed it, anyway. 😄

Edit: another small PR before 1.0 would be to remove the deprecated Wikimate::debugCurlConfig().

[panda87]

Where is @glatomer to approve it?
He is the maintainer, isn't he?

[Xymph]

Where is @glatomer to approve it?
He is the maintainer, isn't he?

galtomer (not gla...) only set up the package on Packagist but it turned out I was also able to update it after creating an account. So we're good.

[panda87]

Cool. I was afraid we will need to wait for him... he is not too responsive for some reason

[Xymph]

Re. v1.0.0, a major version bump is also required when making API breaking changes. If error handling/exceptions are changed (#113) and/or debug logging is changed into levels (already suggested in #101), then those should be completed before the bump to 1.0, as it would be awkward to bump to 2.0.0 soon after.

[Xymph]

Didn't want to post this sooner so as not to distract @waldyrious from more important matters (:smile:) but here are my plans for the next few releases (all code for 0.15.0 already prepared):

• wrap up v0.14.0 (it's big enough and includes requested fixes)

---

• fix user agent format (Fix user agent format; add refs & changelog entry #121)
• address Fix repeated CSRF token fetching #115
• add logout method (Add method Wikimate::logout() #124)
• add file revert methods (Add methods WikiFile::revert() and Wikimate::filerevert() #123)
• wrap up v0.15.0

---

• Remove deprecated method Wikimate::debugCurlConfig #128
• fix Fix error return values in WikiPage::getSection and setText #116
• change login() error code to 'auth' (Change Wikimate::login() error code from 'login' to 'auth' #132)
• use consistent error return / exception pattern (Add WikimateException and centralize API error checks in request()  #136) and resolve Centralize API request/response debug logging and response decoding #113; describe in Usage.md
• switch to composer 2, if that's something we need to do in the package? nope
• change globals.php invocation into Composer's autoload.php (Rewrite installation and invocation instructions using Composer #140)
• wrap up v1.0.0

---

• implement supported parameter mechanism based on paraminfo API request (Added internal mechanism to handle version-dependent parameters of API modules #151)
• support deletetalk parameter in delete page & file methods (Support deletetalk parameter in WikiPage::delete() and WikiFile::delete() #152)
• support undelete API request (Add new method Wikimate::undelete() #153)
• wrap up v.1.1.0

---

• address Place PHP documentation tree on GitHub Pages #110
• support siteinfo API request?
• apply JSON format version 2?
• support exclusion standard
• file usage methods?
• page revisions per Feature Request: Add history for pages too #82?
• authentication support (Feature request: Basic auth authentication #89, Feature request: OAuth authorization #87)?
• more classes for categories, searching, users?
• restructure into multiple source files, somewhat like the abandoned branches (OOP rewrite #75)?

Any feedback?

[waldyrious]

Sounds great to me! Looking forward to the documentation part, where I suspect I might be able to help a bit more. The authentication feature would be a pretty nice addition too.

[Xymph]

Well, these probably were the three most productive days in Wikimate's history. 😁 Thanks for the quick turn-arounds, @waldyrious 👍

Before we gear up for v1.0.0 (of which some parts will take quite some effort), can you think of any small things that would be nice to have in v0.15.0?
Or @samwilson perhaps?

[waldyrious]

I can't think of anything to add, though I probably am not the best person to ask since I haven't actively used this for quite a while :) let's see if others have ideas.

[samwilson]

I don't know; feature-wise, it feels pretty good. One small thing I noticed the other day was the use of globals.php in README.md — maybe it'd be more in keeping with modern PHP norms to just tell people to require __DIR__.'/vendor/autoload.php';? Composer is pretty common these days, and it's a step that's probably already done in many projects.

[Xymph]

I don't know; feature-wise, it feels pretty good. One small thing I noticed the other day was the use of globals.php in README.md — maybe it'd be more in keeping with modern PHP norms to just tell people to require __DIR__.'/vendor/autoload.php';? Composer is pretty common these days, and it's a step that's probably already done in many projects.

Fair point, I'll have to look into & test that. Seems more suitable for v1.0.0 then.

[Xymph]

Since it would otherwise fly under the radar, I better point out that yesterday I added five new entries to the post v1.0 roadmap above:

• implement supported parameter mechanism based on paraminfo API request
• support deletetalk parameter in delete page & file methods
• support undelete API request
• support siteinfo API request?
• apply JSON format version 2?

With probably more to follow.