View Issue Details

IDProjectCategoryView StatusLast Update
0011156mantisbtapi soappublic2010-02-22 14:34
Reporterrombert Assigned Torombert  
PrioritynormalSeveritymajorReproducibilityalways
Status closedResolutionfixed 
Target Version1.2.0Fixed in Version1.2.0 
Summary0011156: Restore the advanced flag in CustomFieldDefinitionData
Description

3de1678bb7b071dfc243110bae9efab70a2f9850 has removed the advanced field from CustomFieldDefinitionData , but it had the nasty side effect of making clients generating stubs using the 1.2 WSDL not being able to use the stubs against 1.1 repositories.

The proposed solution is to restore the advanced property, but ignore it on the server side.

TagsNo tags attached.

Activities

rombert

rombert

2009-11-11 07:46

reporter   ~0023653

@dhx: I plan on applying the fix described in the issue, for backwards compatibility reasons. Any comments?

dhx

dhx

2009-11-11 07:58

reporter   ~0023654

Is the problem that the SOAP API is no longer sending the advanced field to the client (which is expecting it) and thus poorly designed clients without error checking crash? Or maybe the problem is that a SOAP API 'packet' (or whatever you call them) from a 1.2.x release cannot be sent directly to a 1.1.x release of MantisBT because the 1.1.x release is expecting a value for the 'advanced' field?

Or is the problem that the current 1.3.x SOAP API rejects the advanced field (sent by a client) and doesn't continue processing the rest of the request from the client?

Or something else?

I don't know much about the SOAP API of MantisBT but it sounds to me like it'll break whenever we change the data types or fields attached to bug? Considering that our roadmap has plans to move a fair bit of core functionality out into plugins (time tracking, etc)... will our SOAP API break in those cases too?

rombert

rombert

2009-11-11 08:19

reporter   ~0023655

  1. The main issue here is that adding or removing fields from a defined data type is a breaking change for SOAP. We've added fields before, because stubs generated with a newer version would work with older versions as well, so there is a minor annoyance in regenerating stubs. But other projects do that as well, e.g. JIRA.

So for instance if you have target_version added in 1.2.x you could still use the same stubs for 1.1.x and 1.2.x .

But on the other hand if you remove a field from a data type clients would need to maintain two different sets of stubs - one for the old version, and one for the new version, which is a total pain. Perhaps in dynamic languages, where the stubs are automagically generated at runtime this is not an issue, but for Java and .NET it is.

Right now I'm testing the most recent WSDL against a Mantis 1.1 repository and it fails.

  1. On the other hand, this is not a problem on the server side.

  2. As for attaching schema information from plugins, we need to decide how to handle this. IMO it's OK to have a breaking change in the 1.3 SOAP API, as long as we do it early and communicate this intent clearly, but rather bad to have it in 1.2.x in the release candidate stage.

rombert

rombert

2009-11-24 17:18

reporter   ~0023800

I've reverted this in 1.2.x only. Master will be kept free of BC problems.

vboctor

vboctor

2009-11-24 17:22

manager   ~0023802

Is there a reason why we are OK with break backward compatibility in 1.3.x? I am ok, if there is a decent reason to do so. However, the "advanced" flag removal is not a good enough reason for me.

rombert

rombert

2009-11-24 17:27

reporter   ~0023803

On second thought, you're right. We should maintain the API backwards compatible, so that we an insure a smooth transition to 1.3. I will commit this to master as well after I'm done with a rebase.

dhx

dhx

2009-11-24 17:47

reporter   ~0023804

Shouldn't clients be downloading the WSDL from MantisBT version 1.X.Y and then filling out whatever fields it can. It might know more information than the WSDL requires (the advanced field) but in these cases it just ignores the field completely. It may not know some of the information required in the WSDL and in these cases, the software needs to be updated to provide that additional information.

The approach of always maintaining backwards compatibility doesn't sound sustainable to me. At some point in the future, we'd need to force client applications to make a huge change. Compare that to requiring them to make many smaller adjustments, and I believe the second option is easier to handle.

However I am unfamiliar with SOAP so I may be missing something that wouldn't apply generically to software/release engineering.

rombert

rombert

2009-11-24 18:07

reporter   ~0023805

Shouldn't clients be downloading the WSDL from MantisBT version 1.X.Y and then filling out whatever fields it can.

Axis for one does not work like that, and it's a very widely used for Java applications.

The approach of always maintaining backwards compatibility doesn't sound sustainable to me. At some point in the future, we'd need to force client applications to make a huge change. Compare that to requiring them to make many smaller adjustments, and I believe the second option is easier to handle.

The point is not to refrain from making changes - we have done that when introducing the target_version field and the due_date field for example. But at that point all they needed to do was regenerate the stubs and they would be able to work with both versions, exactly as you suggested above.

The place to break and innovate is the MantisBT web services API 2.0 IMO.

However I am unfamiliar with SOAP so I may be missing something that wouldn't apply generically to software/release engineering.

One feature of SOAP is that deleting a field or a method causes a change which requires clients to maintain a separate set of generated client classes, instead of checking for the version and setting the fields or not.

Axis for Java simply bails out when it does not find a field it was expecting, so clients would need to maintain:

org.example.mantisv1 - 25 stub classes + services
org.example.mantisv2 - 25 stub classes + services

all of those diferring by just one field. Remove another field and we get to

org.example.mantisv3

Please note that this does not happen if the changes only involve adding fields - the mantisv1 stubs would still work and you'd simply get null values.

Related Changesets

MantisBT: master-1.2.x 7dc11790

2009-11-24 17:16

rombert


Details Diff
Fixes 0011156: Restore the advanced flag in CustomFieldDefinitionData

This change was done entirely for backwards compatibility reasons and
will not be ported to the master branch.
Affected Issues
0011156
mod - api/soap/mantisconnect.php Diff File

MantisBT: master d91387b1

2009-11-24 17:16

rombert


Details Diff
Fixes 0011156: Restore the advanced flag in CustomFieldDefinitionData

This change was done entirely for backwards compatibility reasons and
will not be ported to the master branch.
Affected Issues
0011156
mod - api/soap/mantisconnect.php Diff File