[14:03:57] Is it RFC time? [14:08:09] * eprodromou checks [14:08:24] Nope, got my timezone math wrong. [14:21:24] <_joe_> eprodromou: sadly not [14:21:31] <_joe_> it will be so at 11 PM my time [14:46:23] Yikes [17:44:12] Hey all, just a reminder Diego Saez Trumper's talk: How to Compare Text Across Multiple Languages will start in about 20 Min [17:44:15] https://www.youtube.com/watch?v=eaDc_4-TNos [17:44:25] I'll take questions here or on the livestream after the talk [18:00:58] o/ [18:02:37] o/ [18:13:52] shouldn't that be paris - france + portugal = lisbon? [18:14:14] https://rare-technologies.com/word2vec-tutorial/ [18:22:51] vector('Paris') - vector('France') + vector('Italy') results in a vector that is very close to vector('Rome'), from https://code.google.com/archive/p/word2vec/ [18:30:55] question from youtube live chat: "What about sense embeddings ? Wikidata has a sense notion of lexemes. I noticed that sense can also be used to build embeddings" [18:38:42] Thx brendan_campbell! [18:40:21] I am curious how the vectors are computed in the first place .. i know you mentioned cbow and skip-gram as training models for computing these ... and how do you pick the # of dimensions .. is that also an output of the models? [18:42:56] Lucas_WMDE: Do you still have a question you would like me to ask Diego? [18:43:57] I saw your had up at the top :-) [18:44:19] no, I was just excited that the stream started, no question :) [18:44:27] (probably with a 1-2min delay from when it started on your end ^^) [18:49:07] reg my qn .. i suppose that is not easily answerable here .. but, pointer / recommendation for a ref to read more details are welcome. [18:50:14] :-) [18:50:30] dsaez fyi .. about a "bug" in your slide there. :) [18:53:03] subbu: do you want me to ask a ? or do you want diego to answer here? [18:53:23] no, that is good .. i'll followup after. thx [18:53:24] oh NM (I think I just asked this Q) [18:54:06] sounds good! [18:55:20] thanks for the presentation! very interesting, the applications sound exciting :) [18:57:39] ty [18:58:28] subbu, about the dimensions, there a discussion about that on th is class: https://www.youtube.com/watch?v=ERibwqs9p38 [18:58:34] let me find the exact minute. [19:01:08] subbu, is the the next class just here: https://youtu.be/ASn7ExxLZws?t=3781 (1:03:30) [19:01:24] thanks! [20:59:03] all right then [20:59:57] hey eprodromou [21:00:09] hey duesen [21:00:14] give it a minute, these things are usually slow to start [21:00:44] no rush, I was just happy to boot my irccloud account and get my nick back [21:00:55] <_joe_> o/ [21:01:01] <_joe_> \o [21:01:17] \o/ [21:01:19] * _joe_ trying to fake a crowd [21:01:25] #startmeeting [21:01:34] hm, no bot? [21:01:55] o/ (not really here, at the tech-mgt f2f) [21:02:21] * duesen goes off to kick the bot [21:02:26] I'm not able to log in to tools-login, maybe there's something wrong with my .ssh/config [21:03:47] TimStarling: I'm logged in [21:04:07] i just ran jstart ~/bin/meetbot [21:04:14] tends to take a while to join, in my experience [21:04:44] we could also go ahead without the bot, and just manually grep for #info later [21:04:52] <_joe_> yes [21:04:57] ok [21:05:24] did you use jstop? [21:05:26] yes [21:05:47] #startmeting TechCom RFC discussion [21:05:56] #startmeeting TechCom RFC discussion [21:06:00] #topic Core REST API namespace and version [21:06:06] it usually doesn't take a while to join, it should join a second or two after you run the right commands [21:06:07] #link https://phabricator.wikimedia.org/T232485 [21:06:34] you once got the impression that it took a while because I fixed it properly a few minutes after you tried to fix it [21:06:45] heh, that may well be :) [21:07:02] there we go! [21:07:06] #startmeeting TechCom RFC discussion [21:07:06] Meeting started Wed Sep 25 21:07:06 2019 UTC and is due to finish in 60 minutes. The chair is duesen. Information about MeetBot at http://wiki.debian.org/MeetBot. [21:07:06] Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. [21:07:06] The meeting name has been set to 'techcom_rfc_discussion' [21:07:10] #topic Core REST API namespace and version [21:07:14] #link https://phabricator.wikimedia.org/T232485 [21:07:17] right [21:07:56] eprodromou: do you want to give a brief summary of the proposal, and what you want to have discussed or agreed on today? [21:08:07] Hi folks! [21:08:23] So, we're developing REST API functionality built into MediaWiki [21:08:39] Using the rest.php entry point [21:09:04] Because paths play such an important role in REST API interfaces... [21:09:24] ...we want to make sure we get the path patterns correct before we start using this API in production [21:09:42] There are two things we want to talk about today: [21:09:54] 1) Including a version number in the API paths [21:10:11] 2) A namespacing strategy for paths provided by extensions [21:10:16] I'll go at them in order [21:10:40] It's a common design pattern for REST APIs to include a version number in the path [21:10:58] I included some examples in the RFC doc [21:11:15] We'd like to follow a semantic version strategy for the API interface... [21:11:32] ...and include the major version number in the path, as "/v1/" prefix [21:12:06] Meaning, "If you developed your client code to use an API with semantic version 1.x, it should keep working with /v1/" [21:12:25] <_joe_> can I ask questions now? [21:12:29] "...and when we go to /v2/, there will be breaking changes and you need to change your code." [21:12:33] <_joe_> I have a couple [21:12:38] #chair apaskulin [21:12:38] Current chairs: apaskulin duesen [21:12:44] Yes, can you focus on what's already been discussed? [21:12:56] I mean, just the versions for now? [21:13:01] <_joe_> sure [21:13:02] So I don't have to explain the namespaces yet? [21:13:17] <_joe_> now, my question is about how we define "keep working" [21:13:21] Cool then fire away [21:13:34] <_joe_> say we decide to undeploy an extension from a wiki, per community decision [21:13:52] OK, good example [21:13:54] <_joe_> what do we do with the corresponding API? do we need a global version change? [21:14:13] <_joe_> or we just respond 404 or something more appropriate [21:14:15] So you skipped right to extensions [21:14:27] But let's get there [21:14:31] <_joe_> well, it's an easier question for core right [21:14:36] Yes [21:14:37] maybe that question is answered with the "components" paert [21:14:50] we could save it for when we get to that [21:15:01] If we removed a route from the API, that would be a breeaking change and we'd need a new API version [21:15:15] s/breeaking/breaking/ [21:15:30] <_joe_> ok [21:15:41] New major version, I mean [21:16:06] #info We'd like to follow a semantic version strategy for the API interface and include the major version number in the path, as "/v1/" prefix [21:16:23] But if we *add* a route to the api, that's a non-breaking change, because all the other routes should keep working [21:16:24] #info If we removed a route from the API, that would be a breaking change and we'd need a new API version [21:16:31] <_joe_> because I thought we could establish a specific deprecation policy, and define more precisely "keep working" [21:17:28] _joe_: i support that, but do you think it's necessary to establish a deprecation policy in order to agree on a versioning mechanism? it seems to me that's beyond the scoep of this rfc [21:17:42] Right, so if a specific route provided by core should be removed, that would need to keep working for as long as v1 exists, until it is deprecated/removed entirely. [21:17:57] <_joe_> duesen: I think we need to keep that in mind when defining versioning [21:18:05] Well, "deprecated" and "removed" are two different things [21:18:09] I think [21:18:29] deprecated could mean that responsnes include "will be removed in v2" [21:18:32] if we want to remote route 'foo', we'd presumably start by creating v2 without it, and deprecate all of v1. [21:18:37] "Deprecated" means the documentation says not to use it, and suggests alternatives [21:18:52] <_joe_> ok, thanks. This answers my question :) [21:18:54] There might even be some runtime results, like headers or metadata [21:19:22] But once it goes 404 (say), then it's a breaking change and we need to do a major version revision [21:19:35] I think that's pretty standard for semantic version numbers [21:19:45] I have a question about adding routes [21:19:49] #link https://semver.org/ [21:19:55] duesen: yes [21:20:10] how will we go about adding routes that are experimental / unstable / beta, etc? [21:20:30] if they just show up under /v1/ people are bound to assume that they are stable, and changing them would be a breaking change [21:20:34] <_joe_> eheh that was also my next uestion [21:20:36] eprodromou: right, but for clients to be able to migrate away, we'd have to introduce the major version bump first, before we can remove it, so that clients who weren't using the deprecated route don't break overnight, but have time to update the code from v1 to v2. [21:20:42] is that how you envision it? [21:20:51] OK, I've got two questions going [21:20:58] I'm going to take duesen first, then Krinkle [21:21:28] duesen: so I assume you're talking about a public release, not developer versions or beta cluster or something like that [21:21:38] yes [21:22:14] And I think the answer is, if it's in /v1/ it's got to be backwards-compatible, and if not, it's not bound by the same rules [21:22:41] <_joe_> I would distinguish here [21:22:47] <_joe_> what will be in a mediawiki release [21:22:56] <_joe_> and what will be exposed by WMF's production [21:23:08] I said in the committee meeting that I don't support putting "beta" or /v0 in the path, for the same reason that headers starting with X- are no longer encouraged [21:23:09] _joe_ I think you're correct [21:23:19] <_joe_> I see value in letting developers expose experimental/unstable endpoints in production [21:23:20] eprodromou: so you would juist use a different prefix, like /experimental/, for "v1 plus experimental stuff"? [21:23:25] I think it is fair to expect that if a new route appears under /v1/ today on wikipedia.org, that will remain stable for developers to use. [21:23:41] <_joe_> duesen: I have a different proposal, as I said coming from kubernetes [21:23:44] and follow normal deprecation/announcements before being changed or removed. [21:23:47] <_joe_> Krinkle: not necessarily [21:23:54] duesen: I don't know if I'm the right person to ask that question [21:24:03] the /v0 path will become a defacto standard, and then you are stuck supporting it forever, and the normal situation is that "unstable" deployed endpoints become stable without modification [21:24:06] <_joe_> Krinkle: we could allow new endpoints to be marked "alpha" or "beta" [21:24:15] <_joe_> in the docs /and/ the responses [21:24:27] Almost by definition, the paths that I am involved in are going to be "official" [21:24:47] <_joe_> so that client developers would know when the new endpoints can be considered stable [21:25:02] <_joe_> and they can still be exposed to the public for fast iteration and feedback collection [21:25:05] Umm, can we do a queue? This is a lot of threads [21:25:07] eprodromou: you don't want to grant yourself the freedom of public experiments that don't require a major version bump to correct mistakes? [21:25:13] <_joe_> eprodromou: sorry, yes [21:25:33] Hm.. right, so there would be a separate mechanism or social principle for how stable it is separate from the path version. so a route in /v1/ can be removed without notice or undergo breaking changes until it has reached stable state [21:25:40] #info TimStarling> I said in the committee meeting that I don't support putting "beta" or /v0 in the path, for the same reason that headers starting with X- are no longer encouraged [21:25:53] #info I think it is fair to expect that if a new route appears under /v1/ today on wikipedia.org, that will remain stable for developers to use. [21:26:21] <_joe_> #info _joe_ we could allow new endpoints to be marked "alpha" or "beta" in the docs and the responsed, to allow fast iteration and feedback collection [21:26:36] #info <_joe_>: we could allow new endpoints to be marked "alpha" or "beta" in the docs /and/ the responses [21:26:44] _joe_: heh [21:26:46] duesen: so, that's a fair question. I think there are going to be different levels of commitment there. [21:26:47] * Krinkle agrees out-of-bound markings for stability would make sense, that would address my concern. [21:27:27] perhaps enforced via an opt-in header to see experimental features, but might not be worth the overhead, proabbly out of scope for the RFC. [21:27:32] duesen: for example, if I have to RFC every endpoint we make, but also need to make APIs for Product to use, that puts me in a bit of a schedule bind. [21:27:36] <_joe_> In my experience as a user of an api using that codification, it's very useful and clarifies the contract a lot, while giving me the ability to give feedback on what works and what sucks :P [21:27:54] All right so I guess we're not doing a queue [21:27:59] eprodromou: can we agree that we should have a standard, documented and discoverable way of indicating that an endpoint is unstable? [21:28:17] <_joe_> eprodromou: sorry you're right [21:28:26] Can we talk about the extension namespaces first, and then come back to unstable interfaces? [21:28:34] ok, let's do that [21:28:40] components and extensions, then [21:28:59] So, "/v1/" is for MediaWiki core. [21:29:15] Extensions will need to provide their paths under a namespace prefix [21:29:30] So "/popups/" or "/confirmedit/" [21:29:45] [queue] 0 (duesen): unstable interfaces (started), 1 (krinkle): how to deprecate/remove, 2 (joe) stability promise wmf vs MW stable [21:30:16] It's recommended but not required to use "v" in the extension paths, too, and follow the same form of versioning [21:30:23] <_joe_> Krinkle: let's stay on the component and extensions :) [21:30:34] <_joe_> o/ [21:30:36] so /confirmedit/v1/captcha [21:30:38] Krinkle: meetbot should have a feature for that :) [21:30:53] OK, I think I'm done with extension namespaces [21:30:59] yeah no worries, I'm just keeping track it's 3Q not 1Q to get back to. no rush [21:31:10] <_joe_> ok I guess I'm first in queue [21:31:15] #info Extensions will need to provide their paths under a namespace prefix, so "/popups/" or "/confirmedit/" [21:31:22] #info It's recommended but not required to use "v" in the extension paths, too, and follow the same form of versioning [21:31:34] <_joe_> my recomendation will be to make it mandatory for extensions to use the same versioning structure [21:32:30] <_joe_> eprodromou: why do you prefer to make it recommended, not required? Any use-case in mind? [21:32:31] +1 if we want to allow third parties to develop internal APis with no stability thing, they could stay on v0 always or some such as placeholder, might make client libraries easier to develop if this is a required part of the url, less ambiguity? [21:32:50] _joe_: primarily to keep it simple [21:33:03] we could require it for all extensions that we deploy [21:33:08] we can't control other extensions anyway [21:33:11] duesen: +1 [21:33:18] Well... [21:33:29] We do control the routing logic [21:33:38] I think simplicity to some extent cuts both ways. It's not popular to say, but I think having some hard rules makes it more simple and new-developer friendly in the long-term. [21:33:44] <_joe_> eprodromou: in my experience, developers hae it easier when standards are well defined and strict. [21:33:50] <_joe_> Krinkle: heheh [21:33:55] it feels inconsistent to me that core wouldn't have an explicitly named component... or why wouldn't core sort things into multiple components [21:34:00] I'd defer to TimStarling on this [21:34:09] RFCs can establish policies that extensions are supposed to follow [21:34:16] <_joe_> Nikerabbit: it would really be redundant. [21:34:26] <_joe_> and ugly as a client developer [21:34:47] I don't think it's worth diving into enforceability unless there is a specific technical proposal for making it more enforceable [21:34:52] TimStarling: could we introduce a mechanism that makes it so that extension routes always have a prefix and version? [21:35:04] <_joe_> (I have another q once I can go again) [21:35:08] I agree we can't require by convention what an extension developer will and will not do, I assumed there would be some actual code in core dealing with component/:version/:path, but if our API is component/:paths, then I suppose making it optional is sensible. [21:35:18] I'm only oppositing that we maintain, in code, an optional concept of component version. [21:35:20] TimStarling: like, extension.json has to have a "rest-prefix" and "rest-api-version" defined, and the router uses those to build routes? [21:35:25] this was proposed in the routing API but rejected [21:35:40] in the routing RFC I mean [21:35:41] eprodromou: some clarifying questions: (1) does this mean *only* extensions can define component prefixes, or could core also do that, if it wanted to have some APIs versioend separately? (2) is it forbidden for extensiosn to add something under the core namespace? [21:35:43] Right, that's true [21:35:52] so no, I don't think we should revisit that decision [21:35:59] TimStarling thanks [21:36:36] #info making 'version' a first class primitive between 'component' and 'paths' was proposed in the REST routing RFC and rejected [21:36:37] TimStarling could we put a check before mounting a route that it included a namespace and version number? [21:37:13] TimStarling: I'm trying to answer the question, "Could we make it mandatory and enforced by code" [21:37:19] _joe_: fair enough, I just thought it might be confusing to end users why something is v1/foo and something else is bar/v1 [21:37:45] <_joe_> Nikerabbit: that's my next q :) [21:38:00] OK, should we address that? [21:38:05] eprodromou: I'm not sure what it would look like but we can develop that outside this meeting [21:38:19] Clearly, there's an asymmetry between core and extensions in this model [21:38:22] we should move on to the other questions considering that we are already at 38 minutes [21:38:28] Right, if we don't make it mandatory and don't recognise it within the REST codebase as a meaningful separator, that also means we can't enforce technically where in the path it might appear. But I think a social policy would suffice for that. [21:38:30] But core and extensions are asymmetrical [21:39:01] in what way would 'core' be more than one of the namespaces (sibling to an extension) [21:39:02] <_joe_> eprodromou: as I said on the RFC task, as a client user I would expect all the resources related to a revision to be under a common path. But with extensions that will not be possible in your proposal, right? [21:39:05] Nikerabbit: earlier proposals had a "/core/" prefix but it's actually pretty uncommon [21:39:06] Krinkle: +1 for social policy [21:39:37] _joe_: that's mostly right [21:39:40] <_joe_> (I would go as far as to use /ext/ to scope them) [21:39:48] _joe_: i'd like that, but then you can't undeploy the extension. [21:39:50] <_joe_> eprodromou: I am kinda happy with my SRE hat on [21:40:01] <_joe_> for what duesen ust said :D [21:40:06] yeah, this means we're departing from the Query API concept of additional page-related extensions being 'nested' within the core/revision API. [21:40:20] duesen pointed out that we could support that mechanism as long as the extension stuck with our version policy [21:40:35] I like separating that out. It might make batching a bit harder though. We'd possibly need an alternate means of connecting related APIs, has that been considered? [21:40:52] eprodromou: and we don't undeploy the extension. which means the versioning would be for the site, not for the software. which further complicates things [21:41:04] duesen: that's right [21:41:18] actually, we should clarify that. does mediawiki dictate the api version? or is it defiend by the site's config? [21:41:31] I think MediaWiki does [21:41:31] I think it would help keep things simple if extensions fundamentally don't have an ability to inject or modify built-in routes. [21:41:37] <_joe_> yes, that's unmanageable duesen please no :D [21:41:43] <_joe_> eprodromou: +1 [21:41:45] ok. [21:41:46] I'll be honest, I don't like having the extensions mount endpoints in the core namespace [21:41:56] #info the API version is defined by the software version, not by site config [21:42:00] We might want to allow inheriting a common class and effectively expose a clone of a core API if really neeeded, but that would be hidden from the client's perspective. [21:42:33] we are running out of time, and we have a couple of questions in the queue still [21:42:40] and likewise not allow extensions to modify each other's routes either. [21:42:45] <_joe_> eprodromou: I kind of agree for maintainability. But one thing I would like to have is /v1/revision/124433 to provide me links to the related endpoints in the enabled extensions [21:42:46] [queue] 0 (duesen): unstable interfaces (started), 1 (krinkle): how to deprecate/remove, 2 (joe) stability promise wmf vs MW stable [21:42:49] Are you still chair, duesen? [21:42:50] i gather that we agree that extensions can't inject anything into the core namespace` [21:42:53] Ah, there we go [21:43:01] eprodromou: i'm trying to chair, yes :) [21:43:14] OK, as long as you're managing the queue, I'm really falling behind [21:43:28] OK, is the front of the queue 0? [21:43:30] I'm relying on Krinkle for that :) [21:43:41] I delegate to duessen to call push() and pop() [21:43:46] hehe [21:43:50] I'll start with 0 [21:44:03] So, one way to deal with unstable interfaces is to start them as an extension... [21:44:13] Krinkle: maybe we can combine "unstable" and "deprecated"? I suspect they could use the same mechanism [21:44:14] ...and then as they become more stable, integrate to core. [21:44:27] if my q becomes obsolete, I will forfeit the slot yes [21:44:37] #info i gather that we agree that extensions can't inject anything into the core namespace [21:44:43] For example, "/audio/v0/sound/12345/play" ... [21:44:57] Which eventually becomes "/v1/sound/12345/play" [21:44:58] #info ...because that would make it impossibel to undeploy the extension. [21:45:03] And that's a made-up example [21:45:17] #info one way to deal with unstable interfaces is to start them as an extension, and then as they become more stable, integrate to core. [21:45:29] eprodromou: i like that. [21:45:53] <_joe_> eprodromou: I would prefer urls not to change when the new endpoint reaches stability [21:45:55] I think I agree with TimStarling that having a designated trashcan for endpoints is probably a source of headaches [21:46:22] _joe_: but I think that's the definition of "unstable" [21:46:25] <_joe_> so I would prefer for the alpha/beta/experimental status to be marked in the response, rather [21:46:33] we've generally followed a model that core should have the same priviledges as an extension, and that an extension should be able to make itself as small or big as it likes, e.g. able to merge two extension repos without being required to change functionality or public routes, as much as possible. [21:46:40] eprodromou: it was also proposed that we could indicate the "deprecated" status in the documentation and in the resposne (and maybe headers) [21:46:43] <_joe_> it will make the chance I have to change my client code much smaller [21:46:52] ... we could do the same with an "unstable" status [21:46:55] _joe_: when you say in the response, do you mean in headers or in JSON? [21:47:04] I assume that means an extension would be permitted to register, say 2 distinct components. [21:47:09] <_joe_> TimStarling: that's a detail right? [21:47:18] sure [21:47:18] Krinkle: I think yes [21:47:43] <_joe_> TimStarling: I am not strongly opinionanted about that, but usually it's part of the schema version for objects returned from the endpoint, yes [21:48:17] <_joe_> whether we're talking of simple json apis, xml, protobuf, whatever [21:48:19] instability and deprecation will presumably be exposed in the self-documentation endpoint, but work on self-documentation has not yet started [21:48:42] <_joe_> so I think docs + clear mark in the response is more than ok from a client prespective [21:48:46] Agreed. Until that point, we'll have documentation-documentation [21:49:11] <_joe_> eprodromou: and that's fine too. I expect this to become an issue well after we have self-documentation :) [21:49:30] it sounds like we're saying experimental endpoints are allowed under v1+ if we mark them as unstable, but we're also saying they should go in an extension under a component with v0. [21:49:43] Krinkle, no I don't think we're saying that [21:49:51] eprodromou: do you think indicating unstable status and deprecation in the response itself is sensible or desirable? Or would you rather not have that? [21:50:00] <_joe_> Krinkle: no I am arguining against changing urls :) [21:50:05] I think we are saying unstable goes in extension with v0 (probably) [21:50:18] _joe_ and I think the answer to that is "don't use unstable interfaces" [21:50:42] eprodromou: but doesn't that have the v0 problem that TimStarling was trying to avoid? [21:50:47] <_joe_> eprodromou: no I am saying that we should not go that route [21:51:03] <_joe_> I say a new endpoint should be introduced where we expect it will be on the long term [21:51:12] duesen: I think what TimStarling was saying was that we shouldn't have a single all-purpose prefix for all unstable stuff [21:51:14] <_joe_> and be marked as unstable/alpha/beta/stable [21:51:18] in the action API there are internal endpoints, I guess we can also have those in the REST API? [21:51:22] .. and mark as unstable until we're sure, during which tiem breaking changes are allowed. [21:51:34] internal means it can change whenever without deprecation [21:51:37] <_joe_> Krinkle: yes that's what I am saying [21:51:42] eprodromou: i don't see what difference that makes in practice... [21:52:05] ok, we are running out of time, we have like five minutes to wrap up [21:52:06] duesen: it means we'd have multiple garbage buckets [21:52:09] <_joe_> eprodromou: we're not in agreement on how to handle experimental endpoints :) [21:52:24] eprodromou: yea, but the enpoints in them are no less prone to be come standard, and unchangeable. [21:52:25] <_joe_> unless I misunderstood your position [21:52:40] overall, it seems like the proposal was perceived favorable [21:52:41] OK, so, the best way is no experimental endpoints exposed publicly [21:53:16] it also seems like we need some clarity on how experimental endpoints should be marked as such, and how they would become official [21:53:34] how do we get feedback without public trials? [21:53:35] similarly, we may want to have some idea of how deprecation should be handled [21:53:49] or would that be behind an authentication token of some kind [21:54:27] <_joe_> Krinkle: hence my proposal, kubernetes launches new interfaces early to gather feedback on what is useless and/or needed from the community [21:54:49] <_joe_> same thing with other infra software I use [21:55:01] for what it's worth, I don't mind major version bumps around deprecation/removal. was just wondering what the proposal says about it [21:55:07] <_joe_> I think it's a good way also to free the developers to iterate and make mistakes [21:55:18] Krinkle: it says major version bump on removal [21:55:32] Do we do a vote on the proposal as it stands? [21:55:37] <_joe_> to be clear, that wouldn't apply to my initial example [21:55:39] Does the RFC need to be amended to include something about experimental and/or deprecated endpoints? [21:55:45] or can this be left for later? [21:55:49] Aside: the task description talks about minor version numbers, but those don't seem to be exposed anywhere. Was the plan to remove minor versions completely or have them appear somewhere else than in the path? [21:55:51] <_joe_> eprodromou: not without clarifications about the new/deprecation endpoints [21:56:05] yes, but I'm not clear on how that is intended in practice. If we want to remove v1/foo today we cannot introduce v2/ without foo and remove all of v1 at the same time, that would break all clients without ability to prepare first. [21:56:13] <_joe_> also things don't get voted here [21:56:21] I assume the intend would be to introduce v2 first, then deprecate v1 and remove it later. [21:56:25] Nikerabbit: they don't appear in the path, but they're part of how semantic versions work [21:56:25] this is getting frantic ;) [21:56:29] * duesen is waving his arms [21:56:29] It is [21:56:38] 3.5 minutes remaining [21:56:41] * eprodromou listens to duesen [21:56:45] thus requiring clients that don't use the deprecated route to upgrade their code in-between, makes sense :) [21:56:50] sssoooo.... [21:57:17] let me ask again: Does the RFC need to be amended to include something about experimental and/or deprecated endpoints? or can this be left for later? [21:57:26] _joe_ said yes it needs that [21:57:33] so I guess it needs it [21:57:42] eprodromou: is that OK with you? [21:57:42] I would argue strongly against including experimental endpoints in the /v1/ namespace [21:57:46] <_joe_> duesen: In my opinion, yes [21:57:46] It might not need nomininal changes, but certainly worth making more explicit [21:57:53] We would be throwing out semantic versioning that way [21:58:05] eprodromou: _joe_'s idea is just to have stability in the response [21:58:06] <_joe_> eprodromou: not really, no. [21:58:14] I would also prefer to see that. if it's in the path or the response or header or whatever. there needs to be a clear indicator [21:58:21] Right [21:58:29] It's in the path with the version number [21:58:32] say have a top-level JSON object element called "stability" set to something [21:58:50] <_joe_> duesen: I am arguing having it in the api is inconvenient, but I'm not against it [21:58:53] #info RFC to be amended to include information on how to indicate unstable (and deprecated?) endpoints. [21:58:56] <_joe_> I just want it to be a clear path [21:59:08] <_joe_> sorry in the path, not in the api [21:59:11] <_joe_> :) [21:59:24] OK, happy to update the RFC to indicate that you should put unstable paths in extensions [21:59:27] <_joe_> so that a developer knows how they can introduce a new interface [21:59:38] #info OK, happy to update the RFC to indicate that you should put unstable paths in extensions [21:59:42] And not in the versioned interface [21:59:44] the version number is not a stability policy [21:59:56] OK [22:00:16] <_joe_> eprodromou: discussion can continue on-task, sure [22:00:21] ok. anything else to resolve in the last 17 seconds? [22:00:36] too late ;) [22:00:38] <_joe_> lol [22:00:40] #endmeeting [22:00:42] your clock is slow [22:00:42] Thanks everyone [22:00:51] the bot has died [22:00:52] I dont think it's against SemVer, in that one can exempt from that by saying it's not public stable, thus not governed by it. Most major software that follows SemVer will ship experimental features it reserves the right to change or break in minor version until it settles. The alternative is to advertise the experimental feature as if it were stable with the major version changing very often, which can be messy. [22:00:53] Meeting ended Wed Sep 25 22:00:53 2019 UTC. Information about MeetBot at http://wiki.debian.org/MeetBot . (v 0.1.4) [22:00:53] Minutes: https://tools.wmflabs.org/meetbot/wikimedia-office/2019/wikimedia-office.2019-09-25-21.07.html [22:00:53] Minutes (text): https://tools.wmflabs.org/meetbot/wikimedia-office/2019/wikimedia-office.2019-09-25-21.07.txt [22:00:53] Minutes (wiki): https://tools.wmflabs.org/meetbot/wikimedia-office/2019/wikimedia-office.2019-09-25-21.07.wiki [22:00:54] Log: https://tools.wmflabs.org/meetbot/wikimedia-office/2019/wikimedia-office.2019-09-25-21.07.log.html [22:01:12] eprodromou: believe it or not, this has been one of the more structured rfc discussions we have had here :D [22:01:44] let's take the discussion on unstable stuff to the task [22:02:11] implied is that everything we didn't talk about is awesome and uncontroversial. [22:02:16] worth saying I suppose :) [22:02:41] apaskulin: I usually copy the minutes generated by meetbot to the task, and link the full log. Want to do that? [22:02:43] * Krinkle is excited by the Rest API [22:02:54] \o/ [22:03:03] will do! [22:03:11] apaskulin: thank you! [22:03:43] Krinkle: indeed. these meetings are always focussed on the problems, the good stuff is hardly mentioned. [22:04:04] eprodromou: maybe if you could clarify the wording related to minor versions... "minor version numbers should be incremented"... if we are not actually incrementing anything or even tracking it [22:04:33] Nikerabbit: i also wondered about that, and then I assumed it would be in the self-documentation [22:04:50] apaskulin: I think chairing properly includes the kinds of things Krinkle was doing, i.e. collecting questions, reminding people of the current topic [22:05:45] sometimes chair just means running the meetbot commands, but that leads to an unstructured discussion [22:06:09] that makes sense. i'll add that to the facilitator's guide [22:06:32] It also helps when the chair isn't as invested in the RFC at hand. Sometimes that can be a fellow TechCom member, but there weren't as many around today. [22:07:12] no critisism on Daniel here, it's hard, and I think it was done well, but hard to beat someone who's focussed only on chairing. And I really want Daniel's input on todays' rfc :) [22:07:56] Krinkle: thanks for doing that [22:07:59] duesen: if it's important, imho we should have checks that it is actually incremented when new stuff is added... if it's not important, prolly not worth spend the human labour on incrementing it [22:08:18] yea, i'm not a good chair, because I tend to be too invested. And when I'm not invested, I get bored and stop following ;) [22:08:43] good night to Europeans :) [22:08:49] Focusing the conversation and ensuring all the important point are discussed and resolved is what a good chair does. I usually fail at that. [22:08:56] bye! [22:09:00] Nikerabbit: bye!