From sflaniga at redhat.com Wed Dec 3 02:14:02 2014 From: sflaniga at redhat.com (Sean Flanigan) Date: Wed, 03 Dec 2014 12:14:02 +1000 Subject: [zanata-devel] Approach to implementing locale mappings REST endpoint In-Reply-To: <1447616643.23321872.1417563567322.JavaMail.zimbra@redhat.com> References: <363878131.17456895.1417562921915.JavaMail.zimbra@redhat.com> <1447616643.23321872.1417563567322.JavaMail.zimbra@redhat.com> Message-ID: <547E71EA.1070002@redhat.com> (Moving discussion to zanata-devel...) On 2014-12-03 09:39, Patrick Huang wrote: > From what I can recall, it is put under "editor" package because > it's only used by the new editor at the moment. Since the new > editor is still in development therefore it will keep in that > package for a while. We *will* be migrating towards new REST api > once the new editor and new REST endpoints are stable enough(you > may have noticed the new template pattern "project/{projectSlug}" > vs the old template pattern "projects/p/{projectSlug} or > proj/{projectSlug}"). Why exactly are we setting up a parallel API hierarchy? We shouldn't need to have three different URL conventions for project resources. I didn't create the convention, and /projects/p/{projectSlug} is a little ugly, but it does allows us to have both /projects (list of projects) and say, /projects/owner/ (projects belonging to ), etc. In any case, I don't think it's bad enough to justify having multiple competing conventions. > Once this https://github.com/zanata/zanata-client/pull/37 is merged > in, we no longer need an interface in client to make a REST call (no > more proxies). No more automatically generated proxies, you mean. It still makes sense to define an interface for Java-based clients to share. > So it's fine you add new endpoints to it. I am not > sure about enunciate documentations. I think once the specific api is > stable enough (like this one?) it's worth adding an enunciate > interface to api. Moving packages later on won't affect the enunciate > doc users. But it will affect Java users. If we have API which we expect to change, a common pattern (eg from Eclipse) is to put it into a package like org.zanata.rest.service.internal or org.zanata.rest.service.experimental, which makes it clear that it might change. (Another option is @Beta tags, as used in Guava and GS Collections.) However, if we're talking about using this particular bit of API in the zanata client, we need to solidify it now, because changing it will break our own client. (Pretty much what David said in his followup email.) I suggest we should move at least the required endpoint into zanata-common-api/org.zanata.rest.service. I think we should err on the side of making all REST APIs visible in zanata-common-api by default (eg for use in scripting, integration, testing), although if they are not needed by the client we could consider putting them into the package org.zanata.rest.service.internal initially. However, if any of these APIs aren't conforming to the existing URL convention, we should fix that before putting them into zanata-common-api. > Patrick Huang > Senior Software Engineer > Engineering - Internationalisation > Red Hat > > ----- Original Message ----- >> From: "David Mason" >> To: "zanata-dev-internal" >> Sent: Wednesday, December 3, 2014 9:28:41 AM >> Subject: [zanata-dev-internal] Approach to implementing locale mappings REST endpoint >> >> I am working on sorting out the REST endpoint for locales with mappings, for >> https://bugzilla.redhat.com/show_bug.cgi?id=1156236 and have found the >> location of the code a bit odd, so I want to check that I am not about to do >> something inappropriate with it. >> >> There is an existing endpoint at >> {server}/rest/project/{projectSlug}/version/{versionSlug}/locales to get a >> list of locales for a version. >> >> It looks like all the REST endpoints for the editor are not declared in >> zanata-api, so they don't get enunciate documentation and are not available >> to clients based on our api library. They are all nested under the namespace >> `org.zanata.rest.editor`, which does not seem ideal to me since the data >> they provide is relevant in contexts other than the editor (e.g. this >> feature in the client). Does someone know if the new endpoints are >> intentionally kept out of the API package? If so, is it because they are too >> volatile at the moment? >> >> The existing endpoint would be fine for the purpose of this story - it just >> needs an optional field for the mapping, if present. I am loath to add a new >> endpoint when we already have one which is fine and is using the most >> appropriate URL pattern, so if there are no objections I will modify the >> existing endpoint, move it out of the `editor` package since there is >> nothing editor-specific about looking up locales, and move its declaration >> to zanata-api. >> >> >> Cheers, >> >> David Mason >> Software Engineer >> L10n Engineering >> >> Red Hat, Asia-Pacific Pty Ltd >> Level 1, 193 North Quay >> Brisbane 4000 >> >> > -- Sean Flanigan Senior Software Engineer Engineering - Internationalisation Red Hat -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 213 bytes Desc: OpenPGP digital signature URL: From sflaniga at redhat.com Wed Dec 3 02:48:44 2014 From: sflaniga at redhat.com (Sean Flanigan) Date: Wed, 03 Dec 2014 12:48:44 +1000 Subject: [zanata-devel] Some exceptional backports to maintenance Hibernate Search releases Message-ID: <547E7A0C.6010007@redhat.com> Some exceptional backports to maintenance Hibernate Search releases http://in.relation.to/Bloggers/SomeExceptionalBackportsToMaintenanceHibernateSearchReleases Looks like we might be able to get a performance boost by upgrading Hibernate Search to 4.4.6.Final or 4.5.2.Final With Hibernate Search 5 it might become viable to use Infinispan 7 for the HS back-end after all. Ref https://github.com/zanata/zanata-server/pull/577 -- Sean Flanigan Senior Software Engineer Engineering - Internationalisation Red Hat -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 213 bytes Desc: OpenPGP digital signature URL: From damason at redhat.com Wed Dec 3 04:27:02 2014 From: damason at redhat.com (David Mason) Date: Tue, 2 Dec 2014 23:27:02 -0500 (EST) Subject: [zanata-devel] Approach to implementing locale mappings REST endpoint In-Reply-To: <547E71EA.1070002@redhat.com> References: <363878131.17456895.1417562921915.JavaMail.zimbra@redhat.com> <1447616643.23321872.1417563567322.JavaMail.zimbra@redhat.com> <547E71EA.1070002@redhat.com> Message-ID: <583652963.17514849.1417580822531.JavaMail.zimbra@redhat.com> ----- Original Message ----- > From: "Sean Flanigan" > To: "Patrick Huang" , "David Mason" > Cc: "zanata-devel" > Sent: Wednesday, 3 December, 2014 12:14:02 PM > Subject: Re: Approach to implementing locale mappings REST endpoint > > (Moving discussion to zanata-devel...) > > On 2014-12-03 09:39, Patrick Huang wrote: > > From what I can recall, it is put under "editor" package because > > it's only used by the new editor at the moment. Since the new > > editor is still in development therefore it will keep in that > > package for a while. We *will* be migrating towards new REST api > > once the new editor and new REST endpoints are stable enough(you > > may have noticed the new template pattern "project/{projectSlug}" > > vs the old template pattern "projects/p/{projectSlug} or > > proj/{projectSlug}"). > > Why exactly are we setting up a parallel API hierarchy? We shouldn't > need to have three different URL conventions for project resources. The new API endpoint locations, at least when I was proposing them, were intended to be the first steps in moving to a more sensible API layout - the new endpoints should just be aliases to the old endpoints where appropriate, and the old endpoints should be deprecated when the new version is stable. I don't know anything about the "proj/{projectSlug}" URL structure. I believe most of the discussion around this can be found here: https://github.com/zanata/fake-zanata-server/pull/5 > > I didn't create the convention, and /projects/p/{projectSlug} is a > little ugly, but it does allows us to have both /projects (list of > projects) and say, /projects/owner/ (projects belonging to > ), etc. In any case, I don't think it's bad enough to justify > having multiple competing conventions. The new scheme does not preclude that structure, since the full namespace for project slugs is available after the singular, whereas the plural is used for anything relating to multiple projects: - .../projects - summary data of all projects, same as in the old schema. - .../projects/{anything} - full namespace available for sub-categories under projects, such as /owner/{username}. Note that "p" is not available here if we want to keep backwards compatibility. - .../project/{projectSlug} - data about an individual project - .../project/{projectSlug}/{anything} - full namespace available for sub-categories under an individual project, such as locales, versions, single version. - .../project/{projectSlug}/versions - summary data about all the versions under a project - .../project/{projectSlug}/version/{versionSlug} - data about an individual version The important thing is not to have ambiguity between identifiers (usernames, slugs, etc.), so I have been careful to ensure that it is always clear from the preceding URL parts what is expected. > > Once this https://github.com/zanata/zanata-client/pull/37 is merged > > in, we no longer need an interface in client to make a REST call (no > > more proxies). > > No more automatically generated proxies, you mean. It still makes sense > to define an interface for Java-based clients to share. > > > So it's fine you add new endpoints to it. I am not > > sure about enunciate documentations. I think once the specific api is > > stable enough (like this one?) it's worth adding an enunciate > > interface to api. Moving packages later on won't affect the enunciate > > doc users. > > But it will affect Java users. If we have API which we expect to > change, a common pattern (eg from Eclipse) is to put it into a package > like org.zanata.rest.service.internal or > org.zanata.rest.service.experimental, which makes it clear that it might > change. (Another option is @Beta tags, as used in Guava and GS > Collections.) > > However, if we're talking about using this particular bit of API in the > zanata client, we need to solidify it now, because changing it will > break our own client. (Pretty much what David said in his followup email.) > > I suggest we should move at least the required endpoint into > zanata-common-api/org.zanata.rest.service. > > I think we should err on the side of making all REST APIs visible in > zanata-common-api by default (eg for use in scripting, integration, > testing), although if they are not needed by the client we could > consider putting them into the package org.zanata.rest.service.internal > initially. > > However, if any of these APIs aren't conforming to the existing URL > convention, we should fix that before putting them into zanata-common-api. I agree with most of the above, but here would argue for having all new endpoint URLs conform to the new URL scheme. A gradual transition to the new scheme is a far less risky approach than a big-bang transition later. We have been complaining for years about the existing URL scheme but I doubt there will ever be a good time to schedule a big transition, so we've started fixing it in a way that does not cause any problems for clients of the existing endpoints. Cheers, David Mason Software Engineer L10n Engineering Red Hat, Asia-Pacific Pty Ltd Level 1, 193 North Quay Brisbane 4000 > > Patrick Huang > > Senior Software Engineer > > Engineering - Internationalisation > > Red Hat > > > > ----- Original Message ----- > >> From: "David Mason" > >> To: "zanata-dev-internal" > >> Sent: Wednesday, December 3, 2014 9:28:41 AM > >> Subject: [zanata-dev-internal] Approach to implementing locale mappings > >> REST endpoint > >> > >> I am working on sorting out the REST endpoint for locales with mappings, > >> for > >> https://bugzilla.redhat.com/show_bug.cgi?id=1156236 and have found the > >> location of the code a bit odd, so I want to check that I am not about to > >> do > >> something inappropriate with it. > >> > >> There is an existing endpoint at > >> {server}/rest/project/{projectSlug}/version/{versionSlug}/locales to get a > >> list of locales for a version. > >> > >> It looks like all the REST endpoints for the editor are not declared in > >> zanata-api, so they don't get enunciate documentation and are not > >> available > >> to clients based on our api library. They are all nested under the > >> namespace > >> `org.zanata.rest.editor`, which does not seem ideal to me since the data > >> they provide is relevant in contexts other than the editor (e.g. this > >> feature in the client). Does someone know if the new endpoints are > >> intentionally kept out of the API package? If so, is it because they are > >> too > >> volatile at the moment? > >> > >> The existing endpoint would be fine for the purpose of this story - it > >> just > >> needs an optional field for the mapping, if present. I am loath to add a > >> new > >> endpoint when we already have one which is fine and is using the most > >> appropriate URL pattern, so if there are no objections I will modify the > >> existing endpoint, move it out of the `editor` package since there is > >> nothing editor-specific about looking up locales, and move its declaration > >> to zanata-api. > >> > >> > >> Cheers, > >> > >> David Mason > >> Software Engineer > >> L10n Engineering > >> > >> Red Hat, Asia-Pacific Pty Ltd > >> Level 1, 193 North Quay > >> Brisbane 4000 > >> > >> > > > > > -- > Sean Flanigan > > Senior Software Engineer > Engineering - Internationalisation > Red Hat > > From sflaniga at redhat.com Thu Dec 4 04:28:59 2014 From: sflaniga at redhat.com (Sean Flanigan) Date: Thu, 04 Dec 2014 14:28:59 +1000 Subject: [zanata-devel] Approach to implementing locale mappings REST endpoint In-Reply-To: <583652963.17514849.1417580822531.JavaMail.zimbra@redhat.com> References: <363878131.17456895.1417562921915.JavaMail.zimbra@redhat.com> <1447616643.23321872.1417563567322.JavaMail.zimbra@redhat.com> <547E71EA.1070002@redhat.com> <583652963.17514849.1417580822531.JavaMail.zimbra@redhat.com> Message-ID: <547FE30B.8010709@redhat.com> On 2014-12-03 14:27, David Mason wrote: > ----- Original Message ----- >> From: "Sean Flanigan" >> To: "Patrick Huang" , "David Mason" >> Cc: "zanata-devel" >> Sent: Wednesday, 3 December, 2014 12:14:02 PM >> Subject: Re: Approach to implementing locale mappings REST endpoint >> Why exactly are we setting up a parallel API hierarchy? We shouldn't >> need to have three different URL conventions for project resources. > > The new API endpoint locations, at least when I was proposing them, > were intended to be the first steps in moving to a more sensible API > layout - the new endpoints should just be aliases to the old > endpoints where appropriate, and the old endpoints should be > deprecated when the new version is stable. I don't know anything > about the "proj/{projectSlug}" URL structure. I believe most of the > discussion around this can be found here: > https://github.com/zanata/fake-zanata-server/pull/5 Thanks. But I think that discussion really ought to have been on this list. A pull request on fake-zanata-server is not the best place to rework zanata-server's API and URL scheme. >> I didn't create the convention, and /projects/p/{projectSlug} is a >> little ugly, but it does allows us to have both /projects (list of >> projects) and say, /projects/owner/ (projects belonging to >> ), etc. In any case, I don't think it's bad enough to justify >> having multiple competing conventions. > > The new scheme does not preclude that structure, since the full > namespace for project slugs is available after the singular, whereas > the plural is used for anything relating to multiple projects: > > - .../projects - summary data of all projects, same as in the old schema. > - .../projects/{anything} - full namespace available for sub-categories under projects, such as /owner/{username}. Note that "p" is not available here if we want to keep backwards compatibility. > - .../project/{projectSlug} - data about an individual project > - .../project/{projectSlug}/{anything} - full namespace available for sub-categories under an individual project, such as locales, versions, single version. > - .../project/{projectSlug}/versions - summary data about all the versions under a project > - .../project/{projectSlug}/version/{versionSlug} - data about an individual version > > The important thing is not to have ambiguity between identifiers > (usernames, slugs, etc.), so I have been careful to ensure that it is > always clear from the preceding URL parts what is expected. Okay, it seems to be a decent scheme, and I don't greatly mind the fact that /project/{projectSlug} would no longer appear under its parent container /projects, since it does make the individual URLs slightly shorter and cleaner. Incidentally, the container relationship would be unimportant if our new API (and consumers) were to follow RESTful HATEOAS principles [1] better. In fact, such clients needn't care about the most of the URLs at all, since they would be handed out by the server as links, not generated in the client. However, I think HATEOAS might be overkill for us at present, since we're not quite on Level 2 of the Richardson Maturity Model[2]. I'm not convinced URL neatness is adequate justification (HATEOAS might be) but if we're planning to change the URLs for existing services, what's the plan for having both .../project/{projectSlug} and .../projects/p/{projectSlug} available in the same server during the deprecation period? We've discussed some ideas about this in the past, but as far as I know we haven't settled on anything as a team. I suppose what I'm saying is this: 1. *If* we're going to change the REST schema, let's get it right. Perhaps we should follow HATEOAS principles, emphasising media-types and links but de-emphasising well-known URL patterns. At the very least we ought to set up a better way of evolving API versions. Otherwise we might be doing this all over again too soon. 2. We need to plan the transition from the old schema to the new one, before starting the transition. Having different project-related resources under different schemas would make the API more complex, so we need a way of deprecating the old API whilst supporting the new. >>> Once this https://github.com/zanata/zanata-client/pull/37 is merged >>> in, we no longer need an interface in client to make a REST call (no >>> more proxies). >> >> No more automatically generated proxies, you mean. It still makes sense >> to define an interface for Java-based clients to share. >> >>> So it's fine you add new endpoints to it. I am not >>> sure about enunciate documentations. I think once the specific api is >>> stable enough (like this one?) it's worth adding an enunciate >>> interface to api. Moving packages later on won't affect the enunciate >>> doc users. >> >> But it will affect Java users. If we have API which we expect to >> change, a common pattern (eg from Eclipse) is to put it into a package >> like org.zanata.rest.service.internal or >> org.zanata.rest.service.experimental, which makes it clear that it might >> change. (Another option is @Beta tags, as used in Guava and GS >> Collections.) >> >> However, if we're talking about using this particular bit of API in the >> zanata client, we need to solidify it now, because changing it will >> break our own client. (Pretty much what David said in his followup email.) >> >> I suggest we should move at least the required endpoint into >> zanata-common-api/org.zanata.rest.service. >> >> I think we should err on the side of making all REST APIs visible in >> zanata-common-api by default (eg for use in scripting, integration, >> testing), although if they are not needed by the client we could >> consider putting them into the package org.zanata.rest.service.internal >> initially. >> >> However, if any of these APIs aren't conforming to the existing URL >> convention, we should fix that before putting them into zanata-common-api. > > I agree with most of the above, but here would argue for having all > new endpoint URLs conform to the new URL scheme. A gradual transition > to the new scheme is a far less risky approach than a big-bang > transition later. It does have the risk of creating patchwork APIs though. As long as we properly deprecate the old APIs before removing them, there needn't be any big bang. I'm not saying we should switch all Zanata's REST URLs to a new scheme at the same time, but if we're switching to /project/{projectSlug} we should make sure all related URLs are switched together, lest we increase the complexity of the API for clients. > We have been complaining for years about the > existing URL scheme What were the specific complaints? My main complaint has been the difficulty in evolving the APIs, not the length of the URLs. > but I doubt there will ever be a good time to > schedule a big transition, so we've started fixing it in a way that > does not cause any problems for clients of the existing endpoints. I guess that depends on the approach we take to deprecation. Have we got a good solution for endpoint aliases? And I don't think we return warnings to old clients doing a version check yet. We really should. Regards Sean. [1] https://en.wikipedia.org/wiki/HATEOAS [2] http://martinfowler.com/articles/richardsonMaturityModel.html -- Sean Flanigan Senior Software Engineer Engineering - Internationalisation Red Hat -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 213 bytes Desc: OpenPGP digital signature URL: From damason at redhat.com Tue Dec 9 01:40:40 2014 From: damason at redhat.com (David Mason) Date: Mon, 8 Dec 2014 20:40:40 -0500 (EST) Subject: [zanata-devel] Approach to implementing locale mappings REST endpoint In-Reply-To: <547FE30B.8010709@redhat.com> References: <363878131.17456895.1417562921915.JavaMail.zimbra@redhat.com> <1447616643.23321872.1417563567322.JavaMail.zimbra@redhat.com> <547E71EA.1070002@redhat.com> <583652963.17514849.1417580822531.JavaMail.zimbra@redhat.com> <547FE30B.8010709@redhat.com> Message-ID: <1012318936.19657950.1418089240810.JavaMail.zimbra@redhat.com> ----- Original Message ----- > From: "Sean Flanigan" > To: "David Mason" > Cc: "Patrick Huang" , "zanata-devel" > Sent: Thursday, 4 December, 2014 2:28:59 PM > Subject: Re: Approach to implementing locale mappings REST endpoint > > On 2014-12-03 14:27, David Mason wrote: > > ----- Original Message ----- > >> From: "Sean Flanigan" > >> To: "Patrick Huang" , "David Mason" > >> > >> Cc: "zanata-devel" > >> Sent: Wednesday, 3 December, 2014 12:14:02 PM > >> Subject: Re: Approach to implementing locale mappings REST endpoint > > >> Why exactly are we setting up a parallel API hierarchy? We shouldn't > >> need to have three different URL conventions for project resources. > > > > The new API endpoint locations, at least when I was proposing them, > > were intended to be the first steps in moving to a more sensible API > > layout - the new endpoints should just be aliases to the old > > endpoints where appropriate, and the old endpoints should be > > deprecated when the new version is stable. I don't know anything > > about the "proj/{projectSlug}" URL structure. I believe most of the > > discussion around this can be found here: > > https://github.com/zanata/fake-zanata-server/pull/5 > > Thanks. But I think that discussion really ought to have been on this > list. A pull request on fake-zanata-server is not the best place to > rework zanata-server's API and URL scheme. > > > >> I didn't create the convention, and /projects/p/{projectSlug} is a > >> little ugly, but it does allows us to have both /projects (list of > >> projects) and say, /projects/owner/ (projects belonging to > >> ), etc. In any case, I don't think it's bad enough to justify > >> having multiple competing conventions. > > > > The new scheme does not preclude that structure, since the full > > namespace for project slugs is available after the singular, whereas > > the plural is used for anything relating to multiple projects: > > > > - .../projects - summary data of all projects, same as in the old schema. > > - .../projects/{anything} - full namespace available for sub-categories > > under projects, such as /owner/{username}. Note that "p" is not available > > here if we want to keep backwards compatibility. > > - .../project/{projectSlug} - data about an individual project > > - .../project/{projectSlug}/{anything} - full namespace available for > > sub-categories under an individual project, such as locales, versions, > > single version. > > - .../project/{projectSlug}/versions - summary data about all the versions > > under a project > > - .../project/{projectSlug}/version/{versionSlug} - data about an > > individual version > > > > The important thing is not to have ambiguity between identifiers > > (usernames, slugs, etc.), so I have been careful to ensure that it is > > always clear from the preceding URL parts what is expected. > > Okay, it seems to be a decent scheme, and I don't greatly mind the fact > that /project/{projectSlug} would no longer appear under its parent > container /projects, since it does make the individual URLs slightly > shorter and cleaner. > > Incidentally, the container relationship would be unimportant if our new > API (and consumers) were to follow RESTful HATEOAS principles [1] > better. In fact, such clients needn't care about the most of the URLs > at all, since they would be handed out by the server as links, not > generated in the client. However, I think HATEOAS might be overkill for > us at present, since we're not quite on Level 2 of the Richardson > Maturity Model[2]. > > > I'm not convinced URL neatness is adequate justification (HATEOAS might > be) but if we're planning to change the URLs for existing services, > what's the plan for having both > .../project/{projectSlug} > and > .../projects/p/{projectSlug} > available in the same server during the deprecation period? We've > discussed some ideas about this in the past, but as far as I know we > haven't settled on anything as a team. > > > I suppose what I'm saying is this: > > 1. *If* we're going to change the REST schema, let's get it right. > Perhaps we should follow HATEOAS principles, emphasising media-types and > links but de-emphasising well-known URL patterns. > > At the very least we ought to set up a better way of evolving API > versions. Otherwise we might be doing this all over again too soon. > > 2. We need to plan the transition from the old schema to the new one, > before starting the transition. Having different project-related > resources under different schemas would make the API more complex, so we > need a way of deprecating the old API whilst supporting the new. > > >>> Once this https://github.com/zanata/zanata-client/pull/37 is merged > >>> in, we no longer need an interface in client to make a REST call (no > >>> more proxies). > >> > >> No more automatically generated proxies, you mean. It still makes sense > >> to define an interface for Java-based clients to share. > >> > >>> So it's fine you add new endpoints to it. I am not > >>> sure about enunciate documentations. I think once the specific api is > >>> stable enough (like this one?) it's worth adding an enunciate > >>> interface to api. Moving packages later on won't affect the enunciate > >>> doc users. > >> > >> But it will affect Java users. If we have API which we expect to > >> change, a common pattern (eg from Eclipse) is to put it into a package > >> like org.zanata.rest.service.internal or > >> org.zanata.rest.service.experimental, which makes it clear that it might > >> change. (Another option is @Beta tags, as used in Guava and GS > >> Collections.) > >> > >> However, if we're talking about using this particular bit of API in the > >> zanata client, we need to solidify it now, because changing it will > >> break our own client. (Pretty much what David said in his followup > >> email.) > >> > >> I suggest we should move at least the required endpoint into > >> zanata-common-api/org.zanata.rest.service. > >> > >> I think we should err on the side of making all REST APIs visible in > >> zanata-common-api by default (eg for use in scripting, integration, > >> testing), although if they are not needed by the client we could > >> consider putting them into the package org.zanata.rest.service.internal > >> initially. > >> > >> However, if any of these APIs aren't conforming to the existing URL > >> convention, we should fix that before putting them into zanata-common-api. > > > > I agree with most of the above, but here would argue for having all > > new endpoint URLs conform to the new URL scheme. A gradual transition > > to the new scheme is a far less risky approach than a big-bang > > transition later. > > It does have the risk of creating patchwork APIs though. > > As long as we properly deprecate the old APIs before removing them, > there needn't be any big bang. > > I'm not saying we should switch all Zanata's REST URLs to a new scheme > at the same time, but if we're switching to /project/{projectSlug} we > should make sure all related URLs are switched together, lest we > increase the complexity of the API for clients. I need to start implementation of these endpoints today. On balance, I think the safest approach will be to add /projects/p/{projectSlug}/locales since that is consistent with the existing URL scheme, and would map directly to /project/{projectSlug}/locales if or when we make project/{projectSlug} an alias of projects/p/{projectSlug} - I may have a brief look at whether there is a lightweight way to add such an alias, and add anything I find to this thread. Cheers, David Mason Software Engineer L10n Engineering Red Hat, Asia-Pacific Pty Ltd Level 1, 193 North Quay Brisbane 4000 > > We have been complaining for years about the > > existing URL scheme > > What were the specific complaints? My main complaint has been the > difficulty in evolving the APIs, not the length of the URLs. > > > but I doubt there will ever be a good time to > > schedule a big transition, so we've started fixing it in a way that > > does not cause any problems for clients of the existing endpoints. > > I guess that depends on the approach we take to deprecation. Have we > got a good solution for endpoint aliases? And I don't think we return > warnings to old clients doing a version check yet. We really should. > > > Regards > > Sean. > > > [1] https://en.wikipedia.org/wiki/HATEOAS > [2] http://martinfowler.com/articles/richardsonMaturityModel.html > > > -- > Sean Flanigan > > Senior Software Engineer > Engineering - Internationalisation > Red Hat > > From damason at redhat.com Tue Dec 9 23:45:16 2014 From: damason at redhat.com (David Mason) Date: Tue, 9 Dec 2014 18:45:16 -0500 (EST) Subject: [zanata-devel] Approach to implementing locale mappings REST endpoint In-Reply-To: <1012318936.19657950.1418089240810.JavaMail.zimbra@redhat.com> References: <363878131.17456895.1417562921915.JavaMail.zimbra@redhat.com> <1447616643.23321872.1417563567322.JavaMail.zimbra@redhat.com> <547E71EA.1070002@redhat.com> <583652963.17514849.1417580822531.JavaMail.zimbra@redhat.com> <547FE30B.8010709@redhat.com> <1012318936.19657950.1418089240810.JavaMail.zimbra@redhat.com> Message-ID: <684477063.20656505.1418168716973.JavaMail.zimbra@redhat.com> ----- Original Message ----- > From: "David Mason" > To: "zanata-devel" > Sent: Tuesday, 9 December, 2014 11:40:40 AM > Subject: Re: [zanata-devel] Approach to implementing locale mappings REST endpoint > ... I may have a brief look at whether there > is a lightweight way to add such an alias, and add anything I find to this > thread. It looks like multiple paths to the same resource is easy to achieve, using a regular expression variable. For the paths: .../projects/p/{projectSlug} .../project/{projectSlug} We could use something like this: @Path(REST_PATH + "/{prefix:project(s/p)?}/{projectSlug}") This would match both the paths, and would give @PathParam("prefix") which may be handy for tracking how often each alternative is being used. See: http://docs.jboss.org/resteasy/docs/1.0.2.GA/userguide/html_single/index.html#_Path_and_regular_expression_mappings Cheers, David Mason Software Engineer L10n Engineering Red Hat, Asia-Pacific Pty Ltd Level 1, 193 North Quay Brisbane 4000 From camunoz at redhat.com Tue Dec 9 23:55:28 2014 From: camunoz at redhat.com (Carlos Munoz) Date: Wed, 10 Dec 2014 09:55:28 +1000 Subject: [zanata-devel] Approach to implementing locale mappings REST endpoint In-Reply-To: <684477063.20656505.1418168716973.JavaMail.zimbra@redhat.com> References: <363878131.17456895.1417562921915.JavaMail.zimbra@redhat.com> <1447616643.23321872.1417563567322.JavaMail.zimbra@redhat.com> <547E71EA.1070002@redhat.com> <583652963.17514849.1417580822531.JavaMail.zimbra@redhat.com> <547FE30B.8010709@redhat.com> <1012318936.19657950.1418089240810.JavaMail.zimbra@redhat.com> <684477063.20656505.1418168716973.JavaMail.zimbra@redhat.com> Message-ID: <54878BF0.6090402@redhat.com> Could we just create two java methods, each mapped to each of the url options, and have them call some common logic? We would need to make sure both options work (not entirely sure how resteasy determines which one to apply. Maybe it goes in order testing the reg exps). That way we keep the urls a bit more readable. There's also the fact that in the api documentation 'prefix' would not show up automatically. We could also do it at the urlrewrite level. Again, no docs for the endpoint, but it's transparent to the code. Carlos A. Munoz Software Engineering Supervisor Engineering - Internationalization Red Hat On 12/10/2014 09:45 AM, David Mason wrote: > ----- Original Message ----- >> From: "David Mason" >> To: "zanata-devel" >> Sent: Tuesday, 9 December, 2014 11:40:40 AM >> Subject: Re: [zanata-devel] Approach to implementing locale mappings REST endpoint > >> ... I may have a brief look at whether there >> is a lightweight way to add such an alias, and add anything I find to this >> thread. > > It looks like multiple paths to the same resource is easy to achieve, using a regular expression variable. > > For the paths: > .../projects/p/{projectSlug} > .../project/{projectSlug} > > We could use something like this: > @Path(REST_PATH + "/{prefix:project(s/p)?}/{projectSlug}") > > This would match both the paths, and would give @PathParam("prefix") which may be handy for tracking how often each alternative is being used. > > > See: http://docs.jboss.org/resteasy/docs/1.0.2.GA/userguide/html_single/index.html#_Path_and_regular_expression_mappings > > > Cheers, > > David Mason > Software Engineer > L10n Engineering > > Red Hat, Asia-Pacific Pty Ltd > Level 1, 193 North Quay > Brisbane 4000 > > _______________________________________________ > zanata-devel mailing list > zanata-devel at redhat.com > https://www.redhat.com/mailman/listinfo/zanata-devel > From damason at redhat.com Wed Dec 10 06:31:33 2014 From: damason at redhat.com (David Mason) Date: Wed, 10 Dec 2014 01:31:33 -0500 (EST) Subject: [zanata-devel] Approach to implementing locale mappings REST endpoint In-Reply-To: <54878BF0.6090402@redhat.com> References: <363878131.17456895.1417562921915.JavaMail.zimbra@redhat.com> <1447616643.23321872.1417563567322.JavaMail.zimbra@redhat.com> <547E71EA.1070002@redhat.com> <583652963.17514849.1417580822531.JavaMail.zimbra@redhat.com> <547FE30B.8010709@redhat.com> <1012318936.19657950.1418089240810.JavaMail.zimbra@redhat.com> <684477063.20656505.1418168716973.JavaMail.zimbra@redhat.com> <54878BF0.6090402@redhat.com> Message-ID: <1250636629.20712780.1418193093898.JavaMail.zimbra@redhat.com> ----- Original Message ----- > From: "Carlos Munoz" > To: "David Mason" , "zanata-devel" > Sent: Wednesday, 10 December, 2014 9:55:28 AM > Subject: Re: [zanata-devel] Approach to implementing locale mappings REST endpoint > > Could we just create two java methods, each mapped to each of the url > options, and have them call some common logic? We would need to make > sure both options work (not entirely sure how resteasy determines which > one to apply. Maybe it goes in order testing the reg exps). To keep things predictable we should make sure the paths are mutually exclusive, so that there is never any guessing which way resteasy will decide to go. It is definitely possible to have two methods that use the same code and give them different paths. An advantage of using a regex in a path is that all sub-paths of project can just be appended to the single path for project, otherwise we would likely have the 2 different paths defined in the project resource, and anything that is nested under project resource would need to append to both URLs and have an alias of each method. > That way we keep the urls a bit more readable. There's also the fact > that in the api documentation 'prefix' would not show up automatically. We can also make a more verbose regex that is easier to read. @Path(REST_PATH + "/{prefix:project|projects/p}/{projectSlug}") We'll have to look into what we can get out of enunciate for documentation - it would be nice if it could show each of the two path structures and indicate that they are equivalent. Cheers, David Mason Software Engineer L10n Engineering Red Hat, Asia-Pacific Pty Ltd Level 1, 193 North Quay Brisbane 4000 > We could also do it at the urlrewrite level. Again, no docs for the > endpoint, but it's transparent to the code. > > Carlos A. Munoz > Software Engineering Supervisor > Engineering - Internationalization > Red Hat > > On 12/10/2014 09:45 AM, David Mason wrote: > > ----- Original Message ----- > >> From: "David Mason" > >> To: "zanata-devel" > >> Sent: Tuesday, 9 December, 2014 11:40:40 AM > >> Subject: Re: [zanata-devel] Approach to implementing locale mappings REST > >> endpoint > > > >> ... I may have a brief look at whether there > >> is a lightweight way to add such an alias, and add anything I find to this > >> thread. > > > > It looks like multiple paths to the same resource is easy to achieve, using > > a regular expression variable. > > > > For the paths: > > .../projects/p/{projectSlug} > > .../project/{projectSlug} > > > > We could use something like this: > > @Path(REST_PATH + "/{prefix:project(s/p)?}/{projectSlug}") > > > > This would match both the paths, and would give @PathParam("prefix") which > > may be handy for tracking how often each alternative is being used. > > > > > > See: > > http://docs.jboss.org/resteasy/docs/1.0.2.GA/userguide/html_single/index.html#_Path_and_regular_expression_mappings > > > > > > Cheers, > > > > David Mason > > Software Engineer > > L10n Engineering > > > > Red Hat, Asia-Pacific Pty Ltd > > Level 1, 193 North Quay > > Brisbane 4000 > > > > _______________________________________________ > > zanata-devel mailing list > > zanata-devel at redhat.com > > https://www.redhat.com/mailman/listinfo/zanata-devel > > > From sflaniga at redhat.com Thu Dec 11 05:31:28 2014 From: sflaniga at redhat.com (Sean Flanigan) Date: Thu, 11 Dec 2014 15:31:28 +1000 Subject: [zanata-devel] Approach to implementing locale mappings REST endpoint In-Reply-To: <1250636629.20712780.1418193093898.JavaMail.zimbra@redhat.com> References: <363878131.17456895.1417562921915.JavaMail.zimbra@redhat.com> <1447616643.23321872.1417563567322.JavaMail.zimbra@redhat.com> <547E71EA.1070002@redhat.com> <583652963.17514849.1417580822531.JavaMail.zimbra@redhat.com> <547FE30B.8010709@redhat.com> <1012318936.19657950.1418089240810.JavaMail.zimbra@redhat.com> <684477063.20656505.1418168716973.JavaMail.zimbra@redhat.com> <54878BF0.6090402@redhat.com> <1250636629.20712780.1418193093898.JavaMail.zimbra@redhat.com> Message-ID: <54892C30.1050103@redhat.com> On 2014-12-10 16:31, David Mason wrote: > ----- Original Message ----- >> From: "Carlos Munoz" >> To: "David Mason" , "zanata-devel" >> Sent: Wednesday, 10 December, 2014 9:55:28 AM >> Subject: Re: [zanata-devel] Approach to implementing locale mappings REST endpoint >> >> Could we just create two java methods, each mapped to each of the url >> options, and have them call some common logic? We would need to make >> sure both options work (not entirely sure how resteasy determines which >> one to apply. Maybe it goes in order testing the reg exps). > > To keep things predictable we should make sure the paths are mutually exclusive, so that there is never any guessing which way resteasy will decide to go. It is definitely possible to have two methods that use the same code and give them different paths. An advantage of using a regex in a path is that all sub-paths of project can just be appended to the single path for project, otherwise we would likely have the 2 different paths defined in the project resource, and anything that is nested under project resource would need to append to both URLs and have an alias of each method. > >> That way we keep the urls a bit more readable. There's also the fact >> that in the api documentation 'prefix' would not show up automatically. > > We can also make a more verbose regex that is easier to read. > > @Path(REST_PATH + "/{prefix:project|projects/p}/{projectSlug}") > > We'll have to look into what we can get out of enunciate for > documentation - it would be nice if it could show each of the two > path structures and indicate that they are equivalent. If we want the ability to deprecate one of the options, they will probably have to be on two different Java methods - Enunciate uses the JavaDoc for a method as the doc for an endpoint. > > > Cheers, > > David Mason > Software Engineer > L10n Engineering > > Red Hat, Asia-Pacific Pty Ltd > Level 1, 193 North Quay > Brisbane 4000 > > >> We could also do it at the urlrewrite level. Again, no docs for the >> endpoint, but it's transparent to the code. >> >> Carlos A. Munoz >> Software Engineering Supervisor >> Engineering - Internationalization >> Red Hat >> >> On 12/10/2014 09:45 AM, David Mason wrote: >>> ----- Original Message ----- >>>> From: "David Mason" >>>> To: "zanata-devel" >>>> Sent: Tuesday, 9 December, 2014 11:40:40 AM >>>> Subject: Re: [zanata-devel] Approach to implementing locale mappings REST >>>> endpoint >>> >>>> ... I may have a brief look at whether there >>>> is a lightweight way to add such an alias, and add anything I find to this >>>> thread. >>> >>> It looks like multiple paths to the same resource is easy to achieve, using >>> a regular expression variable. >>> >>> For the paths: >>> .../projects/p/{projectSlug} >>> .../project/{projectSlug} >>> >>> We could use something like this: >>> @Path(REST_PATH + "/{prefix:project(s/p)?}/{projectSlug}") >>> >>> This would match both the paths, and would give @PathParam("prefix") which >>> may be handy for tracking how often each alternative is being used. >>> >>> >>> See: >>> http://docs.jboss.org/resteasy/docs/1.0.2.GA/userguide/html_single/index.html#_Path_and_regular_expression_mappings >>> >>> >>> Cheers, >>> >>> David Mason >>> Software Engineer >>> L10n Engineering >>> >>> Red Hat, Asia-Pacific Pty Ltd >>> Level 1, 193 North Quay >>> Brisbane 4000 >>> >>> _______________________________________________ >>> zanata-devel mailing list >>> zanata-devel at redhat.com >>> https://www.redhat.com/mailman/listinfo/zanata-devel >>> >> > > _______________________________________________ > zanata-devel mailing list > zanata-devel at redhat.com > https://www.redhat.com/mailman/listinfo/zanata-devel > -- Sean Flanigan Senior Software Engineer Engineering - Internationalisation Red Hat -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 213 bytes Desc: OpenPGP digital signature URL: From damason at redhat.com Fri Dec 12 04:18:07 2014 From: damason at redhat.com (David Mason) Date: Thu, 11 Dec 2014 23:18:07 -0500 (EST) Subject: [zanata-devel] Can't figure out why Seam is losing the conversation In-Reply-To: <39015964.21845199.1418356793265.JavaMail.zimbra@redhat.com> Message-ID: <515890617.21848355.1418357887119.JavaMail.zimbra@redhat.com> I'm stuck on an odd issue with the forms for setting locale aliases. Can someone spot what I'm missing that might be causing this? I have added a form to each language in project -> settings -> languages that just has a textbox and a commandLink. The textbox is bound to a value in a map, mapped by the LocaleId for the row. It works as expected when entering text in one of the textboxes and clicking the commandLink: the value is persisted in the database and updates some text in the UI based on the value. This works fine multiple times for the same language. It fails as soon as the commandLink is pressed for a different language, with a NullPointerException trying to look up the versions in ProjectHome. It seems like it is losing the conversation as soon as the form on a different row is submitted. It does not matter which row is submitted first, and refreshing the page resets the state so that once again any single row can be submitted multiple times. It also seems to put the languages tab in an odd state, so that it will no longer hide when other tabs are selected. Exception: 14:10:11,355 SEVERE [javax.enterprise.resource.webcontainer.jsf.application] (http-/0.0.0.0:8080-1) Error Rendering View[/project/project.xhtml]: javax.el.ELException: /WEB-INF/layout/project/versions-tab.xhtml @113,78 value="#{projectHomeAction.versionFilter.currentPage}": java.lang.NullPointerException ... Caused by: java.lang.NullPointerException at org.zanata.action.ProjectHomeAction.getProjectVersions(ProjectHomeAction.java:399) [classes:] These are all my changes: https://github.com/zanata/zanata-server/compare/locale-aliases The form is defined here: https://github.com/zanata/zanata-server/blob/34a246161f15360d206971283670aaf058b42818/zanata-war/src/main/webapp/WEB-INF/layout/project/settings-tab.xhtml#L310 The method called when the commandLink is clicked is here: https://github.com/zanata/zanata-server/blob/34a246161f15360d206971283670aaf058b42818/zanata-war/src/main/java/org/zanata/action/ProjectHome.java#L228 Cheers, David Mason Software Engineer L10n Engineering Red Hat, Asia-Pacific Pty Ltd Level 1, 193 North Quay Brisbane 4000 From sflaniga at redhat.com Fri Dec 12 04:46:04 2014 From: sflaniga at redhat.com (Sean Flanigan) Date: Fri, 12 Dec 2014 14:46:04 +1000 Subject: [zanata-devel] Can't figure out why Seam is losing the conversation In-Reply-To: <515890617.21848355.1418357887119.JavaMail.zimbra@redhat.com> References: <515890617.21848355.1418357887119.JavaMail.zimbra@redhat.com> Message-ID: <548A730C.2030801@redhat.com> This could be a dumb question, but is the cid parameter being sent to the server with the commandLink's ajax request? Or any other requests you are able to snoop on? On 2014-12-12 14:18, David Mason wrote: > I'm stuck on an odd issue with the forms for setting locale aliases. Can someone spot what I'm missing that might be causing this? > > I have added a form to each language in project -> settings -> languages that just has a textbox and a commandLink. The textbox is bound to a value in a map, mapped by the LocaleId for the row. It works as expected when entering text in one of the textboxes and clicking the commandLink: the value is persisted in the database and updates some text in the UI based on the value. This works fine multiple times for the same language. > > It fails as soon as the commandLink is pressed for a different language, with a NullPointerException trying to look up the versions in ProjectHome. It seems like it is losing the conversation as soon as the form on a different row is submitted. It does not matter which row is submitted first, and refreshing the page resets the state so that once again any single row can be submitted multiple times. It also seems to put the languages tab in an odd state, so that it will no longer hide when other tabs are selected. > > Exception: > 14:10:11,355 SEVERE [javax.enterprise.resource.webcontainer.jsf.application] (http-/0.0.0.0:8080-1) Error Rendering View[/project/project.xhtml]: javax.el.ELException: /WEB-INF/layout/project/versions-tab.xhtml @113,78 value="#{projectHomeAction.versionFilter.currentPage}": java.lang.NullPointerException > ... > Caused by: java.lang.NullPointerException > at org.zanata.action.ProjectHomeAction.getProjectVersions(ProjectHomeAction.java:399) [classes:] > > > These are all my changes: https://github.com/zanata/zanata-server/compare/locale-aliases > > The form is defined here: https://github.com/zanata/zanata-server/blob/34a246161f15360d206971283670aaf058b42818/zanata-war/src/main/webapp/WEB-INF/layout/project/settings-tab.xhtml#L310 > > The method called when the commandLink is clicked is here: https://github.com/zanata/zanata-server/blob/34a246161f15360d206971283670aaf058b42818/zanata-war/src/main/java/org/zanata/action/ProjectHome.java#L228 > > > > Cheers, > > David Mason > Software Engineer > L10n Engineering > > Red Hat, Asia-Pacific Pty Ltd > Level 1, 193 North Quay > Brisbane 4000 > > _______________________________________________ > zanata-devel mailing list > zanata-devel at redhat.com > https://www.redhat.com/mailman/listinfo/zanata-devel > -- Sean Flanigan Senior Software Engineer Engineering - Internationalisation Red Hat -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 213 bytes Desc: OpenPGP digital signature URL: From damason at redhat.com Fri Dec 12 05:34:19 2014 From: damason at redhat.com (David Mason) Date: Fri, 12 Dec 2014 00:34:19 -0500 (EST) Subject: [zanata-devel] Can't figure out why Seam is losing the conversation In-Reply-To: <548A730C.2030801@redhat.com> References: <515890617.21848355.1418357887119.JavaMail.zimbra@redhat.com> <548A730C.2030801@redhat.com> Message-ID: <2070690897.21863795.1418362459443.JavaMail.zimbra@redhat.com> ----- Original Message ----- > From: "Sean Flanigan" > To: "David Mason" , "zanata-devel" > Sent: Friday, 12 December, 2014 2:46:04 PM > Subject: Re: [zanata-devel] Can't figure out why Seam is losing the conversation > > This could be a dumb question, but is the cid parameter being sent to > the server with the commandLink's ajax request? Or any other requests > you are able to snoop on? I tried adding cid to the form manually, but that didn't make any difference. Cheers, David Mason Software Engineer L10n Engineering Red Hat, Asia-Pacific Pty Ltd Level 1, 193 North Quay Brisbane 4000 > On 2014-12-12 14:18, David Mason wrote: > > I'm stuck on an odd issue with the forms for setting locale aliases. Can > > someone spot what I'm missing that might be causing this? > > > > I have added a form to each language in project -> settings -> languages > > that just has a textbox and a commandLink. The textbox is bound to a value > > in a map, mapped by the LocaleId for the row. It works as expected when > > entering text in one of the textboxes and clicking the commandLink: the > > value is persisted in the database and updates some text in the UI based > > on the value. This works fine multiple times for the same language. > > > > It fails as soon as the commandLink is pressed for a different language, > > with a NullPointerException trying to look up the versions in ProjectHome. > > It seems like it is losing the conversation as soon as the form on a > > different row is submitted. It does not matter which row is submitted > > first, and refreshing the page resets the state so that once again any > > single row can be submitted multiple times. It also seems to put the > > languages tab in an odd state, so that it will no longer hide when other > > tabs are selected. > > > > Exception: > > 14:10:11,355 SEVERE > > [javax.enterprise.resource.webcontainer.jsf.application] > > (http-/0.0.0.0:8080-1) Error Rendering View[/project/project.xhtml]: > > javax.el.ELException: /WEB-INF/layout/project/versions-tab.xhtml @113,78 > > value="#{projectHomeAction.versionFilter.currentPage}": > > java.lang.NullPointerException > > ... > > Caused by: java.lang.NullPointerException > > at > > org.zanata.action.ProjectHomeAction.getProjectVersions(ProjectHomeAction.java:399) > > [classes:] > > > > > > These are all my changes: > > https://github.com/zanata/zanata-server/compare/locale-aliases > > > > The form is defined here: > > https://github.com/zanata/zanata-server/blob/34a246161f15360d206971283670aaf058b42818/zanata-war/src/main/webapp/WEB-INF/layout/project/settings-tab.xhtml#L310 > > > > The method called when the commandLink is clicked is here: > > https://github.com/zanata/zanata-server/blob/34a246161f15360d206971283670aaf058b42818/zanata-war/src/main/java/org/zanata/action/ProjectHome.java#L228 > > > > > > > > Cheers, > > > > David Mason > > Software Engineer > > L10n Engineering > > > > Red Hat, Asia-Pacific Pty Ltd > > Level 1, 193 North Quay > > Brisbane 4000 > > > > _______________________________________________ > > zanata-devel mailing list > > zanata-devel at redhat.com > > https://www.redhat.com/mailman/listinfo/zanata-devel > > > > > -- > Sean Flanigan > > Senior Software Engineer > Engineering - Internationalisation > Red Hat > > From damason at redhat.com Mon Dec 15 07:15:56 2014 From: damason at redhat.com (David Mason) Date: Mon, 15 Dec 2014 02:15:56 -0500 (EST) Subject: [zanata-devel] Should locale mappings from project be heritable by project-version? In-Reply-To: <2063941139.22513785.1418627186656.JavaMail.zimbra@redhat.com> Message-ID: <1021477514.22515160.1418627756107.JavaMail.zimbra@redhat.com> An item we overlooked when specifying the locale aliases story. - If there are locale aliases specified for a project, and one of that project's versions has the setting "Inherit languages from project settings.", should it also inherit all the locale aliases? I think the answer is yes, since locale aliases on a project server no purpose other than to be inherited. - If the version does not inherit its languages from the project, when a language is added that has a mapping in the project, should the mapping from the project be added as well? I am not sure about this one. - Some users may want to use the language list from the project, with a few additions or omissions. In that case I think they would want or expect the aliases to be copied in when they add each locale. - Some users may user the project setting for most versions, but have a very old or very new version that uses a different locale scheme. For these users, adding the aliases would probably be an annoyance. Any thoughts on these? For now I will implement inheriting aliases when languages are inherited, and I will not copy aliases when adding individual locales to a version. Cheers, David Mason Software Engineer L10n Engineering Red Hat, Asia-Pacific Pty Ltd Level 1, 193 North Quay Brisbane 4000 From dchen at redhat.com Mon Dec 15 08:07:03 2014 From: dchen at redhat.com (Ding Yi Chen) Date: Mon, 15 Dec 2014 03:07:03 -0500 (EST) Subject: [zanata-devel] Should locale mappings from project be heritable by project-version? In-Reply-To: <1021477514.22515160.1418627756107.JavaMail.zimbra@redhat.com> References: <1021477514.22515160.1418627756107.JavaMail.zimbra@redhat.com> Message-ID: <1619241946.1233191.1418630823139.JavaMail.zimbra@redhat.com> ----- Original Message ----- > An item we overlooked when specifying the locale aliases story. > > - If there are locale aliases specified for a project, and one of that > project's versions has the setting "Inherit languages from project > settings.", should it also inherit all the locale aliases? I think the > answer is yes, since locale aliases on a project server no purpose other > than to be inherited. Yes. otherwise project maintainers will be frustrated to see some languages failed to push or pull after they create a new version. > - Some users may user the project setting for most versions, but have a > very old or very new version that uses a different locale scheme. For > these users, adding the aliases would probably be an annoyance. IMHO, this scenario is quite unlikely. However, if you determine to handle this case, there are 2 ways 1. Use file-mapping rule of zanata.xml in client side. Project maintainers can use this to produce whatever they want. 2. Given we have a checkbox "Inherit langauge from project", project maintainer can disable this and specified their set of mapping. However, this means we have to implement UI for this. Regards, -- Ding-Yi Chen Software Engineer Internationalization Group DID: +61 7 3514 8239 Email: dchen at redhat.com Red Hat, Asia-Pacific Pty Ltd Level 1, 193 North Quay Brisbane 4000 Office: +61 7 3514 8100 Fax: +61 7 3514 8199 Website: www.redhat.com Red Hat, Inc. Facebook: Red Hat APAC | Red Hat Japan | Red Hat Korea | JBoss APAC Twitter: Red Hat APAC | Red Hat ANZ LinkedIn: Red Hat APAC | JBoss APAC From camunoz at redhat.com Mon Dec 15 22:24:28 2014 From: camunoz at redhat.com (Carlos Munoz) Date: Tue, 16 Dec 2014 08:24:28 +1000 Subject: [zanata-devel] Should locale mappings from project be heritable by project-version? In-Reply-To: <1021477514.22515160.1418627756107.JavaMail.zimbra@redhat.com> References: <1021477514.22515160.1418627756107.JavaMail.zimbra@redhat.com> Message-ID: <548F5F9C.9020408@redhat.com> Carlos A. Munoz Software Engineering Supervisor Engineering - Internationalization Red Hat On 12/15/2014 05:15 PM, David Mason wrote: > An item we overlooked when specifying the locale aliases story. > > - If there are locale aliases specified for a project, and one of that project's versions has the setting "Inherit languages from project settings.", should it also inherit all the locale aliases? I think the answer is yes, since locale aliases on a project server no purpose other than to be inherited. I think that's a good assumption. > - If the version does not inherit its languages from the project, when a language is added that has a mapping in the project, should the mapping from the project be added as well? I am not sure about this one. > - Some users may want to use the language list from the project, with a few additions or omissions. In that case I think they would want or expect the aliases to be copied in when they add each locale. Well, currently when they elect to change their list of languages they get an exact copy of the project's list (as that is the effective list). For that reason I'd say we copy the mappings. Having said that, we need to change that screen considerably for it to be much friendlier. > - Some users may user the project setting for most versions, but have a very old or very new version that uses a different locale scheme. For these users, adding the aliases would probably be an annoyance. Yes. But in that case I think it's ok if they need to go through the steps of fine tuning their locale list. I think it's better to avoid duplicating work (having them repeat the definition of the locale aliases defined in the project), than making them define a new custom list of locales (and aliases) for their 'special' versions. > > Any thoughts on these? For now I will implement inheriting aliases when languages are inherited, and I will not copy aliases when adding individual locales to a version. Those are my thoughts: I think we should copy locales for a version. If it's still within the effort estimated. > > Cheers, > > David Mason > Software Engineer > L10n Engineering > > Red Hat, Asia-Pacific Pty Ltd > Level 1, 193 North Quay > Brisbane 4000 > > _______________________________________________ > zanata-devel mailing list > zanata-devel at redhat.com > https://www.redhat.com/mailman/listinfo/zanata-devel > From sflaniga at redhat.com Tue Dec 16 02:45:06 2014 From: sflaniga at redhat.com (Sean Flanigan) Date: Tue, 16 Dec 2014 12:45:06 +1000 Subject: [zanata-devel] Testing clients and servers against each other with Pact Message-ID: <548F9CB2.1090107@redhat.com> Right now we have two different "pretend" versions of the Zanata server (fake-zanata-server for JavaScript and stub-server for Java). That's not even counting GWT's old dummy mode - is anyone using this now? These dummy servers are taking up a fair amount of development and maintenance, but how much do they really tell us about the interaction between our clients and the real Zanata server? And how much maintenance effort will they require as the server changes? Consumer-Driven Contracts[1] come up a lot when discussing microservices, but given the number of clients for Zanata server - - Java (current and old versions) - Python (current and old) - JavaScript - Zanata SPA - clients written by others (eg PHP client, OpenStack integration) - I think we could really benefit from using CDCs right now. One of the microservices talks[2] at the YOW! conference included mention of Pact [3][4] by REA, which enables sharing of CDCs between client and server for HTTP services. Beth Skurrie talked about Test Symmetry, which involves unit testing a consumer against a mock [like fake-server or stub-server], but *recording* the interactions to a pact file, then *verifying* the interactions in the pact file (or files) against the real provider. I think this is a great idea, and a really important one. Before putting much more effort into our fake servers, I really think we should try out Pact for Java [5] and/or for JavaScript [6]. It's possible there will be a bit of a learning curve, but I think the pay-off will be worth it. [1] http://martinfowler.com/articles/consumerDrivenContracts.html [2] http://yowconference.com.au/slides/yow2014/SkurrieBottcherEvans-MonolithsToMicroservices.pdf [3] https://github.com/bethesque/pact-specification (the spec) [4] https://github.com/realestate-com-au/pact (the original) [5] https://github.com/DiUS/pact-jvm (Java) [6] https://github.com/DiUS/pact-consumer-js-dsl (JavaScript clients) PS ThoughtWorks has a similar library called Pacto, but I think Pact has more momentum, with a spec and implementations for multiple languages. -- Sean Flanigan Senior Software Engineer Engineering - Internationalisation Red Hat -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 213 bytes Desc: OpenPGP digital signature URL: From damason at redhat.com Tue Dec 16 04:23:50 2014 From: damason at redhat.com (David Mason) Date: Mon, 15 Dec 2014 23:23:50 -0500 (EST) Subject: [zanata-devel] Testing clients and servers against each other with Pact In-Reply-To: <548F9CB2.1090107@redhat.com> References: <548F9CB2.1090107@redhat.com> Message-ID: <352191434.23123569.1418703830915.JavaMail.zimbra@redhat.com> fake-zanata-server is intended for two purposes: - To allow developers to work on clients without having to go through the significant hassle of deploying a Zanata server on JBoss locally. Someone can clone zanata-spa and run it while remaining in the context of the JavaScript build tools that are used to build the editor (installing node is the most manual part of the process). - To rapidly prototype additions and changes to the REST interface in a context that has very fast builds and a more straightforward way to declare the response bodies. How well does Pact fit each of these purposes? The idea of recording interactions is interesting - if fake-zanata-server has continued utility that might be a useful addition. A quick search shows several Pact packages on npm, so it may be easy to add. Recording client interactions with the real server could provide useful information as well. Cheers, David Mason Software Engineer L10n Engineering Red Hat, Asia-Pacific Pty Ltd Level 1, 193 North Quay Brisbane 4000 ----- Original Message ----- > From: "Sean Flanigan" > To: "zanata-devel" > Sent: Tuesday, 16 December, 2014 12:45:06 PM > Subject: [zanata-devel] Testing clients and servers against each other with Pact > > Right now we have two different "pretend" versions of the Zanata server > (fake-zanata-server for JavaScript and stub-server for Java). That's > not even counting GWT's old dummy mode - is anyone using this now? > > These dummy servers are taking up a fair amount of development and > maintenance, but how much do they really tell us about the interaction > between our clients and the real Zanata server? And how much > maintenance effort will they require as the server changes? > > > Consumer-Driven Contracts[1] come up a lot when discussing > microservices, but given the number of clients for Zanata server - > > - Java (current and old versions) > - Python (current and old) > - JavaScript - Zanata SPA > - clients written by others (eg PHP client, OpenStack integration) > > - I think we could really benefit from using CDCs right now. > > One of the microservices talks[2] at the YOW! conference included > mention of Pact [3][4] by REA, which enables sharing of CDCs between > client and server for HTTP services. > > Beth Skurrie talked about Test Symmetry, which involves unit testing a > consumer against a mock [like fake-server or stub-server], but > *recording* the interactions to a pact file, then *verifying* the > interactions in the pact file (or files) against the real provider. I > think this is a great idea, and a really important one. > > Before putting much more effort into our fake servers, I really think we > should try out Pact for Java [5] and/or for JavaScript [6]. It's > possible there will be a bit of a learning curve, but I think the > pay-off will be worth it. > > > [1] http://martinfowler.com/articles/consumerDrivenContracts.html > [2] > http://yowconference.com.au/slides/yow2014/SkurrieBottcherEvans-MonolithsToMicroservices.pdf > [3] https://github.com/bethesque/pact-specification (the spec) > [4] https://github.com/realestate-com-au/pact (the original) > [5] https://github.com/DiUS/pact-jvm (Java) > [6] https://github.com/DiUS/pact-consumer-js-dsl (JavaScript clients) > > PS ThoughtWorks has a similar library called Pacto, but I think Pact has > more momentum, with a spec and implementations for multiple languages. > > -- > Sean Flanigan > > Senior Software Engineer > Engineering - Internationalisation > Red Hat > > > _______________________________________________ > zanata-devel mailing list > zanata-devel at redhat.com > https://www.redhat.com/mailman/listinfo/zanata-devel From sflaniga at redhat.com Wed Dec 17 04:54:45 2014 From: sflaniga at redhat.com (Sean Flanigan) Date: Wed, 17 Dec 2014 14:54:45 +1000 Subject: [zanata-devel] Testing clients and servers against each other with Pact In-Reply-To: <352191434.23123569.1418703830915.JavaMail.zimbra@redhat.com> References: <548F9CB2.1090107@redhat.com> <352191434.23123569.1418703830915.JavaMail.zimbra@redhat.com> Message-ID: <54910C95.5080507@redhat.com> On 2014-12-16 14:23, David Mason wrote: > fake-zanata-server is intended for two purposes: > > - To allow developers to work on clients without having to go through > the significant hassle of deploying a Zanata server on JBoss locally. > Someone can clone zanata-spa and run it while remaining in the > context of the JavaScript build tools that are used to build the > editor (installing node is the most manual part of the process). > - To rapidly prototype additions and changes to the REST interface in > a context that has very fast builds and a more straightforward way > to declare the response bodies. > How well does Pact fit each of these purposes? From what I can tell, it is certainly intended to address both those problems. (As well as the problem of faked interactions not matching real interactions with the server, naturally.) I have only used pact-jvm, and only in consumer mode so far, not the JavaScript version, but starting the test server was as easy as specifying a port. The response bodies can be created any way you like in the client language. I was initially using a hard-coded XML string, then I switched to a fluent XML builder (Mycila XML Tool), and have now settled on creating DTOs and serialising them via JAXB. I have a pull request with my changes here: https://github.com/zanata/zanata-client/pull/42 Enabling TDD seems to be a primary goal of CDCs, so I think it will address the second point fairly well. There's some information about the JS version's requirements here: https://github.com/DiUS/pact-consumer-js-dsl Oh, and in case you don't want to wade through a 70MB presentation, I found a useful blog post about Pact: http://techblog.realestate.com.au/enter-the-pact-matrix-or-how-to-decouple-the-release-cycles-of-your-microservices/ > The idea of recording interactions is interesting - if > fake-zanata-server has continued utility that might be a useful > addition. A quick search shows several Pact packages on npm, so it > may be easy to add. Recording client interactions with the real > server could provide useful information as well. > > Cheers, > > David Mason > Software Engineer > L10n Engineering > > Red Hat, Asia-Pacific Pty Ltd > Level 1, 193 North Quay > Brisbane 4000 > > ----- Original Message ----- >> From: "Sean Flanigan" >> To: "zanata-devel" >> Sent: Tuesday, 16 December, 2014 12:45:06 PM >> Subject: [zanata-devel] Testing clients and servers against each other with Pact >> >> Right now we have two different "pretend" versions of the Zanata server >> (fake-zanata-server for JavaScript and stub-server for Java). That's >> not even counting GWT's old dummy mode - is anyone using this now? >> >> These dummy servers are taking up a fair amount of development and >> maintenance, but how much do they really tell us about the interaction >> between our clients and the real Zanata server? And how much >> maintenance effort will they require as the server changes? >> >> >> Consumer-Driven Contracts[1] come up a lot when discussing >> microservices, but given the number of clients for Zanata server - >> >> - Java (current and old versions) >> - Python (current and old) >> - JavaScript - Zanata SPA >> - clients written by others (eg PHP client, OpenStack integration) >> >> - I think we could really benefit from using CDCs right now. >> >> One of the microservices talks[2] at the YOW! conference included >> mention of Pact [3][4] by REA, which enables sharing of CDCs between >> client and server for HTTP services. >> >> Beth Skurrie talked about Test Symmetry, which involves unit testing a >> consumer against a mock [like fake-server or stub-server], but >> *recording* the interactions to a pact file, then *verifying* the >> interactions in the pact file (or files) against the real provider. I >> think this is a great idea, and a really important one. >> >> Before putting much more effort into our fake servers, I really think we >> should try out Pact for Java [5] and/or for JavaScript [6]. It's >> possible there will be a bit of a learning curve, but I think the >> pay-off will be worth it. >> >> >> [1] http://martinfowler.com/articles/consumerDrivenContracts.html >> [2] >> http://yowconference.com.au/slides/yow2014/SkurrieBottcherEvans-MonolithsToMicroservices.pdf >> [3] https://github.com/bethesque/pact-specification (the spec) >> [4] https://github.com/realestate-com-au/pact (the original) >> [5] https://github.com/DiUS/pact-jvm (Java) >> [6] https://github.com/DiUS/pact-consumer-js-dsl (JavaScript clients) >> >> PS ThoughtWorks has a similar library called Pacto, but I think Pact has >> more momentum, with a spec and implementations for multiple languages. >> >> -- >> Sean Flanigan >> >> Senior Software Engineer >> Engineering - Internationalisation >> Red Hat >> >> >> _______________________________________________ >> zanata-devel mailing list >> zanata-devel at redhat.com >> https://www.redhat.com/mailman/listinfo/zanata-devel -- Sean Flanigan Senior Software Engineer Engineering - Internationalisation Red Hat -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 213 bytes Desc: OpenPGP digital signature URL: