Added work item type doc

[tsmaeder]

This change is

[kwk]

Hats off! Honestly, you've put quite some thought into this document and I hope you don't mind my many comments. Some of them only fix typos and others evaluate some of your ideas.

---

Review status: 0 of 1 files reviewed at latest revision, 22 unresolved discussions, some commit checks failed.

---

_blueprints/work_item_types.adoc, line 5 [r1] (raw file):

These service in turn are the basis for our UI.

should be

These services in turn are the basis for our UI.

Notice the additional s.

Apart from that I think these services are not the basis for any UI but they are the backend counterpart for any UI talking to the backend, right?

---

_blueprints/work_item_types.adoc, line 7 [r1] (raw file):

There is a central work item (micro-)service that serves as a common platform for storage and query of work items. Client services extend the basic work item types to offer business functionality like different ways of planning (scrum, waterfall, etc.), testing, ideation, etc. These service in turn are the basis for our UI.

== Goals

Maybe the goals should be written as a bulletin point list because it makes it easier to differentiate between them. Currently the sentences seem to have some dependencies on each other which makes it hard to understand a clear goal.

To me it sounds like the goals are:

• Efficiently store work item types in a relational database
• Index on fields
  • By the way: optimizing storage has nothing to do with putting an index on a field. That is optimizing the query at best. And if you don't know the query's WHERE clause upfront you hardly can optimize with any index.
• Enforce a form of work item through a work item type with the benefit of storing efficiently. What does "efficiently" mean here
• Let a UI select only relevant work items by querying for a specific work item type.

To me, the last one is the only relevant point and everything else is technical boilerplate and can be considered a strategy to reach this goal.

---

_blueprints/work_item_types.adoc, line 8 [r1] (raw file):

json

should be

JSON

---

_blueprints/work_item_types.adoc, line 8 [r1] (raw file):

for example setting indices on fields in the work items.

You can also have indices in purely JSON driven databases like MongoDB so that's not a good reason. Well, it is but only in PostgreSQL and that is not mentioned here.

---

_blueprints/work_item_types.adoc, line 12 [r1] (raw file):

The description of a type does not have to be the same as the construction of a type.

What does this mean?

---

_blueprints/work_item_types.adoc, line 23 [r1] (raw file):

• A release (�Neon.2�)
• A version (�3.7.2.Snapshot�)

After the opening and before the closing parenthesis are weird characters.

---

_blueprints/work_item_types.adoc, line 27 [r1] (raw file):

But some things are not, e.g.

• A project
• A user

What about a "team" or an "organization"? Are those work items?

Any why don't we allow clients to extend a project or a user? Maybe somebody would like to store additional information for a user like a photo of a person.

---

_blueprints/work_item_types.adoc, line 33 [r1] (raw file):

A work item is a flat list of fields conforming to a given work item type.

Given that sentence, I'd say we rename type to schema because that is more what a type really is.

---

_blueprints/work_item_types.adoc, line 36 [r1] (raw file):

For example it contains a "required" field

Do you mean that a description contains a map (from string to one of the types below) and that each map entry (aka field) has a "required" option? If that's the case then we should model this out as an extensible field constraint. Such a constraint could then have a callback which returns an error in case the field doesn't correspond to the user's constraint definition. Just as an idea.

---

_blueprints/work_item_types.adoc, line 41 [r1] (raw file):

** Boolean
** Integer

Will be allow 0 to be assigned to a Boolean field?

** String
** Url

Url should be URL...

Can one assign a String to a URL?

Having automatic casts opens to the door to hell IMHO. Trust me, we've been there in my last job when defining our own language. We decided to have default constructors for each type (even for int and float - or should I say: especially for those?!).

What I'm saying is that technically a URL is a String but not the other way around and the same is true for Int and Float.

---

_blueprints/work_item_types.adoc, line 46 [r1] (raw file):

** WorkitemReference·

What's that?

---

_blueprints/work_item_types.adoc, line 50 [r1] (raw file):

• list type
  +
  An ordered list of values of one of the simple types

Why is the ordering important and how will it be achieved or can it be influenced by the user? Will a string list always be sorted in alphanumerical order?

What about lists of user-defined types?

What about a map collection?

What about a set? This could be extremely helpful for membership relationships.

---

_blueprints/work_item_types.adoc, line 52 [r1] (raw file):

• enum type
  +
  A value from among a given list of values of a simple type

I think the last sentence needs a rewrite ;)

---

_blueprints/work_item_types.adoc, line 56 [r1] (raw file):

The set of work item types per Project is expected to be small (< 50) and fixed.

Why is that (for storage optimization) and why is there a limit?

A project hasn't been defined so far, thus making it hard to understand.

---

_blueprints/work_item_types.adoc, line 59 [r1] (raw file):

awaterfall

should be

a waterfall

---

_blueprints/work_item_types.adoc, line 60 [r1] (raw file):

One challenge is to reuse fields where they mean the same thing.

Why take the risk of reusing fields instead of defining only the very basic fields as standard and all others as customization?

---

_blueprints/work_item_types.adoc, line 61 [r1] (raw file):

When we decide to plan our project with a kanban board from now on, we would like to reuse the owner and stare fields.

I'd say that the intelligence of mapping fields to one another shouldn't be deeply buried in the ALM but in a migration step that is exposed to the user and that the user has full control over. Let's choice clever assistance over crappy intelligence. A simply algorithm to do the mapping would be to take kanban and sprint fields and compare them by field name and type. If a field matches in name and type (!!) it is offered for direct migration.

GUI wise think of a form on the left and one on the right. The form fields are wired with lines, letting a user decide what to do with each field.
Consider a scrum and kanban and let's suppose there's a string field S in scrum that cannot be mapped to anything in kanban. The user can now either decide to remove the field and lose all the information or create a new custom string field in the kanban form and wire it up with the string field S from the scrum form.

For this to work with user interaction we should have migration UI wizards.

When switching from scrum to kanban user roles change too and for this to work smoothly we should offer a wired form wizard as well.

---

_blueprints/work_item_types.adoc, line 65 [r1] (raw file):

it is an error.

To avoid errors and let users resolve the mapping issues I have proposed a way in my comment above.

---

_blueprints/work_item_types.adoc, line 69 [r1] (raw file):

like

is not needed because you continue with (think [...])

---

_blueprints/work_item_types.adoc, line 72 [r1] (raw file):

New Types can be added by inheriting from existing types. Fields can be added, but they must conform to the field name rules system-wide. Type inheritance is used to define a special kind of work item that can be used in a new way

This sounds very vague and I'm not sure inheritance is a good idea, especially multiple inheritance.

---

_blueprints/work_item_types.adoc, line 74 [r1] (raw file):

=== Type Extension (Mixins)
Type mixins should be used to extend a type of work items with new fields. This is to address adding cross cutting concerns to a type of work item. For example, one could add fields for time tracking to all work items of the predefined type "task". All work items inheriting from "task" (bug, story, etc.) would inherit the extended fields.

So you're saying that you extend a type along its natural inheritance chain? Now that sounds interesting.

---

_blueprints/work_item_types.adoc, line 78 [r1] (raw file):

=== Queries & Duck Typing
Many times a service will want to query for work items of a given type (for example, a scrum board will want items that have "rank", "owner", "sprint" and "state"). I propose that we use duck typing when evaluating such a query. Concretely, any work item type that includes the same structure as the queried for type will match.

Maybe you should add this:

• Given a type X which contains fields A B C and a type Y containing field A B C D.
• If somebody queries field of type X that one will get all items of type X and Y because Y has all the fields required by X (and one more).
• Whereas if somebody queries field of type Y that one will get all items of type Y only because the type X has no field D.

I have to think about duck typing in an API. Intuitively I'd say it is not a good idea but if we allow for Mixins we have to allow duck typing I guess. No?! :)

---

Comments from Reviewable

[kwk]

Reviewed 1 of 1 files at r1.
Review status: all files reviewed at latest revision, 22 unresolved discussions, some commit checks failed.

---

Comments from Reviewable

[aslakknutsen]

You're thinking that there will be a "Scrum Endpoint" that the UI talk to? The "Scrum Endpoint" then talks to Core backbone?

[aslakknutsen]

_blueprints/work_item_types.adoc, line 7 [r1] (raw file):

in a relational database

That's a storage implementation detail. And unrelated to why we have WorkItem types.

---

Comments from Reviewable

[aslakknutsen]

_blueprints/work_item_types.adoc, line 33 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

A work item is a flat list of fields conforming to a given work item type.

Given that sentence, I'd say we rename type to schema because that is more what a type really is.

Type/Schema/Definition...

---

Comments from Reviewable

[kwk]

Review status: all files reviewed at latest revision, 27 unresolved discussions, some commit checks failed.

---

_blueprints/work_item_types.adoc, line 7 [r1] (raw file):

Previously, aslakknutsen (Aslak Knutsen) wrote…

in a relational database

That's a storage implementation detail. And unrelated to why we have WorkItem types.

I just mentioned this because Thomas didn't specify what efficient storing means.

---

_blueprints/work_item_types.adoc, line 33 [r1] (raw file):

Previously, aslakknutsen (Aslak Knutsen) wrote…

Type/Schema/Definition...

You mentioned schema yourself. The word schema relates more to what we mean and it is **not** a term in Go as well. A type could mistakenly be taken as something in Go whereas schema sounds like its own language domain. I know this is just a detail.

---

Comments from Reviewable

[aslakknutsen]

_blueprints/work_item_types.adoc, line 33 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

You mentioned schema yourself. The word schema relates more to what we mean and it is not a term in Go as well. A type could mistakenly be taken as something in Go whereas schema sounds like its own language domain. I know this is just a detail.

For the sake of completeness, VSO calls them: Work Item Type Definitions :)

---

Comments from Reviewable

[aslakknutsen]

_blueprints/work_item_types.adoc, line 33 [r1] (raw file):

Previously, aslakknutsen (Aslak Knutsen) wrote…

For the sake of completeness, VSO calls them: Work Item Type Definitions :)

And the "Work Item Type Definition" has a XML-Schema.

---

Comments from Reviewable

[tsmaeder]

Review status: all files reviewed at latest revision, 27 unresolved discussions, some commit checks failed.

---

_blueprints/work_item_types.adoc, line 5 [r1] (raw file):

Previously, aslakknutsen (Aslak Knutsen) wrote…

You're thinking that there will be a "Scrum Endpoint" that the UI talk to? The "Scrum Endpoint" then talks to Core backbone?

Yes.

---

_blueprints/work_item_types.adoc, line 5 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

These service in turn are the basis for our UI.

should be

These services in turn are the basis for our UI.

Notice the additional s.

Apart from that I think these services are not the basis for any UI but they are the backend counterpart for any UI talking to the backend, right?

yes

---

_blueprints/work_item_types.adoc, line 7 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

I just mentioned this because Thomas didn't specify what efficient storing means.

If you have knowledge about the possible shape of work items, you can structure your storage accordingly. Indices are one example of how we can prepare for possible queries (you can't query for a field that is not in work item type). Btw: MongoDB knows indices, too: https://docs.mongodb.com/manual/tutorial/optimize-query-performance-with-indexes-and-projections/#create-indexes-to-support-queries One of the complaints that came out of the f2f in Neuchatel was that current systems have bad performance when querying over custom fields. This is my way of addressing that concern.

---

_blueprints/work_item_types.adoc, line 8 [r1] (raw file):

Previously, aslakknutsen (Aslak Knutsen) wrote…

There are a few more reasons for WorkItemType that comes to mind;

• Defines structure
• Defines display names (possible display form)
• Defines state transition model
• Allows validation

Essentially works as a Schema for what you can do with this WorkItem. Storage etc is an impl detail.

I am not sure yet how to model states and state transitions. This might be a point of extension that is orthogonal to work item types. In that thinking work item types are more about storage than operations. The same goes for UI labels for given fields. If work item types are defined system wide, we may have multiple renamings for the same field in a work item type. That would hint that it's not part of the work item type, but something else on the side. If by validation you mean restricting the kind of values you can store, I agree. But validation can also mean help for the user with entering values. I don't think that should be a duty of the work item service.

---

_blueprints/work_item_types.adoc, line 8 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

for example setting indices on fields in the work items.

You can also have indices in purely JSON driven databases like MongoDB so that's not a good reason. Well, it is but only in PostgreSQL and that is not mentioned here.

Yes, in order to set indices, you need to know what fields you have. My argument is in no way about the choice of storage engine.

---

_blueprints/work_item_types.adoc, line 12 [r1] (raw file):

Previously, aslakknutsen (Aslak Knutsen) wrote…

You mean WorkItemTypes can have a parent/child relationship, but a WorkItem is seen as 'flat' ?

No, what I mean is that when I ask the system for a work item type, I might get back a flat list of field descriptions with no indication of how it was constructed. For example, a work item type T might have been constructed by inheriting fields a and b from Type U and adding field c. Clients will likely not be interested in how a field ended up in a work item type, just that it is there. So we when we query for a work item type, we don't need to know about the inheritance or extension most of the time.

---

_blueprints/work_item_types.adoc, line 12 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

The description of a type does not have to be the same as the construction of a type.

What does this mean?

See anwer above.

---

_blueprints/work_item_types.adoc, line 23 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

• A release (�Neon.2�)
• A version (�3.7.2.Snapshot�)

After the opening and before the closing parenthesis are weird characters.

They are "typographic" double quotes copied from google docs. Seems reviewable makes a hash of it (they show up correctly in the github ui).

---

_blueprints/work_item_types.adoc, line 27 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

But some things are not, e.g.

• A project
• A user

What about a "team" or an "organization"? Are those work items?

Any why don't we allow clients to extend a project or a user? Maybe somebody would like to store additional information for a user like a photo of a person.

E.g. == for example, so not an exhaustive list. Users & projects are not work items because for one they are not treated as such here: http://devdoc.almighty.io/blueprints/model_overview.html But also, a user (or principal) is closely tied to authentication & authorisation, so I think it needs to be a first class concept. We don't know much a priori about work items, but we NEED to know a lot about users. About projects: for me the project is a point of configuration of work items, for example, which work item types are allowed indside that project. Perhaps this is not true and the point of configuration is the "organization", but we haven't discussed this deeply yet.

---

_blueprints/work_item_types.adoc, line 33 [r1] (raw file):

Previously, aslakknutsen (Aslak Knutsen) wrote…

And the "Work Item Type Definition" has a XML-Schema.

This document is about the conceptual model of our system. The fact that we have started implementing thes service in golang should not influence our choice of terms here. My feeling is that "type" is more about what operations you can do on a given bit if data, wheres "schema" is more purely structural. Poteto potato.

---

_blueprints/work_item_types.adoc, line 36 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

For example it contains a "required" field

Do you mean that a description contains a map (from string to one of the types below) and that each map entry (aka field) has a "required" option? If that's the case then we should model this out as an extensible field constraint. Such a constraint could then have a callback which returns an error in case the field doesn't correspond to the user's constraint definition. Just as an idea.

I see that as a future point of extension but would like to leave it out for now.

---

_blueprints/work_item_types.adoc, line 41 [r1] (raw file):

Will be allow 0 to be assigned to a Boolean field?

Certainly not! Boolean fields can have the values "true" or "false", which are not numbers.

Can one assign a String to a URL?

I guess we will have to differentiate between (untyped) literals and fields. I haven't thought out the typing rules of a query or expression language yet. Feel free to share your experiences and what what particular torture awaited you in imlicit conversion hell.

---

_blueprints/work_item_types.adoc, line 46 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

** WorkitemReference·

What's that?

A reference to a work item...not sure if this needs to be typed yet.

---

_blueprints/work_item_types.adoc, line 50 [r1] (raw file):

Why is the ordering important and how will it be achieved or can it be influenced by the user? Will a string list always be sorted in alphanumerical order?

We will preserve the order given by the client. Sorting is a derived property and does not need to be specified in the type.

What about lists of user-defined types?

Nope, trying to keep it simple.

What about a map collection?

What's the use case?

What about a set? This could be extremely helpful for membership relationships.

Actually, it's not as useful as it sounds. Because we are useing a read/save model, the client would have to make sure it's not sending duplicates, otherwise the "save" operation would be rejected. So all we can add here is a level of safety.
In general, I don't think offering multiple collection types will help us validate the proposed concept. I propose we try to get a simple model right first and add variations later.

---

_blueprints/work_item_types.adoc, line 52 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

• enum type
  +
  A value from among a given list of values of a simple type

I think the last sentence needs a rewrite ;)

What's wrong with it?

---

_blueprints/work_item_types.adoc, line 56 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

The set of work item types per Project is expected to be small (< 50) and fixed.

Why is that (for storage optimization) and why is there a limit?

A project hasn't been defined so far, thus making it hard to understand.

Project == the configuration point for work process/work item types. It's essential to the idea of duck typing in queries..."type like X" can be compiled to "type in (a, b, c)". If you have millions of types, that doesn't scale.

---

_blueprints/work_item_types.adoc, line 60 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

One challenge is to reuse fields where they mean the same thing.

Why take the risk of reusing fields instead of defining only the very basic fields as standard and all others as customization?

Because we want the ecosystem to reuse their respective work. If there is a "hours worked" field, I want other plugins (for example on to repor to a time trackign system) to reuse that field name and not define their own.

---

_blueprints/work_item_types.adoc, line 61 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

When we decide to plan our project with a kanban board from now on, we would like to reuse the owner and stare fields.

I'd say that the intelligence of mapping fields to one another shouldn't be deeply buried in the ALM but in a migration step that is exposed to the user and that the user has full control over. Let's choice clever assistance over crappy intelligence. A simply algorithm to do the mapping would be to take kanban and sprint fields and compare them by field name and type. If a field matches in name and type (!!) it is offered for direct migration.

GUI wise think of a form on the left and one on the right. The form fields are wired with lines, letting a user decide what to do with each field.
Consider a scrum and kanban and let's suppose there's a string field S in scrum that cannot be mapped to anything in kanban. The user can now either decide to remove the field and lose all the information or create a new custom string field in the kanban form and wire it up with the string field S from the scrum form.

For this to work with user interaction we should have migration UI wizards.

When switching from scrum to kanban user roles change too and for this to work smoothly we should offer a wired form wizard as well.

I disagree...by reusing the "owner" field, we say: "this is the same field". It's not just that it has the same name by chance. Plugins (or services, or whatever) in a certain domain should agree on a common vocabulary.

---

_blueprints/work_item_types.adoc, line 65 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

it is an error.

To avoid errors and let users resolve the mapping issues I have proposed a way in my comment above.

Again, migration is a different issue.

---

_blueprints/work_item_types.adoc, line 72 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

New Types can be added by inheriting from existing types. Fields can be added, but they must conform to the field name rules system-wide. Type inheritance is used to define a special kind of work item that can be used in a new way

This sounds very vague and I'm not sure inheritance is a good idea, especially multiple inheritance.

I'm not proposing multiple inheritance (outside of mixins). Shipping with predefined types ensures minimal content for all kinds of work items.

---

_blueprints/work_item_types.adoc, line 74 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

=== Type Extension (Mixins)
Type mixins should be used to extend a type of work items with new fields. This is to address adding cross cutting concerns to a type of work item. For example, one could add fields for time tracking to all work items of the predefined type "task". All work items inheriting from "task" (bug, story, etc.) would inherit the extended fields.

So you're saying that you extend a type along its natural inheritance chain? Now that sounds interesting.

If it's a duck, it's a bird. Of course it gets wings...

---

_blueprints/work_item_types.adoc, line 75 [r1] (raw file):

Previously, aslakknutsen (Aslak Knutsen) wrote…

Let's assume there is a system provided base WIT that defines a Task. Bug and Story extend Task.

As a User, I want to add Time to Bug and Story. I create a new custom Task that extend the system provided Task and add the Time info.

Should the 'system' know that you have extended a Base type and apply your custom Task WIT when 'resolving' the system provided WIT like Bug and Story.

or

Does the user have to extend the system provided Story and override the 'parent' type to use the new custom Task.

or

Does the user have to 'recreate' the system provided Story and point it's parent to the new custom Task WIT, because you for whatever reason can't override the Parent of a Parent in a Child.

If you make a new type that inherits from the "Task" type, it will not affect "Story" or "Bug" in any way. However, if you write a mixin for the "Task" type, it's like you are patching the "Task" type, and thus all type that extend from it. Of course, this can lead to inconsistencies which we will have to prevent.

---

_blueprints/work_item_types.adoc, line 78 [r1] (raw file):

Previously, aslakknutsen (Aslak Knutsen) wrote…

You mean, pseudo query lang:

Select wi from workitem

where wi.type in(

   select wit from workitemtype

   where wit.fields contain all ("rank", "owner", "sprint", "state") 

) 

?

Yes, in principle. But I would probably do it by defining a "like" operator in the query language ("WHERE workitem.type LIKE MyWIType")

---

_blueprints/work_item_types.adoc, line 78 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

=== Queries & Duck Typing
Many times a service will want to query for work items of a given type (for example, a scrum board will want items that have "rank", "owner", "sprint" and "state"). I propose that we use duck typing when evaluating such a query. Concretely, any work item type that includes the same structure as the queried for type will match.

Maybe you should add this:

• Given a type X which contains fields A B C and a type Y containing field A B C D.
• If somebody queries field of type X that one will get all items of type X and Y because Y has all the fields required by X (and one more).
• Whereas if somebody queries field of type Y that one will get all items of type Y only because the type X has no field D.

I have to think about duck typing in an API. Intuitively I'd say it is not a good idea but if we allow for Mixins we have to allow duck typing I guess. No?! :)

Do you think the paragraph is unclear? The purpose of the document is not to have a formal defintion.

---

Comments from Reviewable

[aslakknutsen]

_blueprints/work_item_types.adoc, line 78 [r1] (raw file):

Previously, tsmaeder (Thomas Mäder) wrote…

Yes, in principle. But I would probably do it by defining a "like" operator in the query language ("WHERE workitem.type LIKE MyWIType")

Sure, if you need the whole workitem.type to match MyWITType. But e.g. a Sprint Query is probably only interested in a subsection of the fields the WIT describe. Assuming, for now, we don't have a 'SprintMixinType' to query for, you could query for a list of 'types/fields' you need the WI's to support/have.

But yea, I see the point.

---

Comments from Reviewable

[kwk]

Review status: all files reviewed at latest revision, 22 unresolved discussions, some commit checks failed.

---

_blueprints/work_item_types.adoc, line 23 [r1] (raw file):

Previously, tsmaeder (Thomas Mäder) wrote…

They are "typographic" double quotes copied from google docs. Seems reviewable makes a hash of it (they show up correctly in the github ui).

They are no ascii double quotes but **angled** double quotes and that makes them problematic.

---

_blueprints/work_item_types.adoc, line 27 [r1] (raw file):

Previously, tsmaeder (Thomas Mäder) wrote…

E.g. == for example, so not an exhaustive list. Users & projects are not work items because for one they are not treated as such here: http://devdoc.almighty.io/blueprints/model_overview.html
But also, a user (or principal) is closely tied to authentication & authorisation, so I think it needs to be a first class concept. We don't know much a priori about work items, but we NEED to know a lot about users.
About projects: for me the project is a point of configuration of work items, for example, which work item types are allowed indside that project. Perhaps this is not true and the point of configuration is the "organization", but we haven't discussed this deeply yet.

Very good explanation and I fully understand it. Thank you very much!!!!

---

_blueprints/work_item_types.adoc, line 36 [r1] (raw file):

Previously, tsmaeder (Thomas Mäder) wrote…

I see that as a future point of extension but would like to leave it out for now.

I learned that Goa does have something for this already. See the `Attribute` API docs: https://goa.design/reference/goa/design/apidsl/#func-attribute-a-name-apidsl-attribute-a

This looks like the possibility to add arbitrary complex validations (that don't required DB access or something) in the design:

Attribute("name", Integer, "description", func() {
    Enum(1, 2)                  // And validation rules
})

---

_blueprints/work_item_types.adoc, line 41 [r1] (raw file):

Feel free to share your experiences and what what particular torture awaited you in imlicit conversion hell.

I suggest to have these types of constructors

func NewURL(u string) (URLType, error)
func NewBoolean(b string) (BooleanType, error)
func NewDuration(uint64 a, uint64 b) (DurationType, error)

and maybe have each type implement a common interface to convert to standard types

type ToString interface {
    func ToString() string
}

// A URL stores all parts of a unified resource location in separated parts
type URL struct {
    protocol string
    user string
    host string
    port uint64
    dir string
    // ...
}

func NewURL(u string) (URL, error) {
    // Decompose from u into part of URL and return
    // ...
}

// ToString returns a string representation of a URL object
func (u URL) ToString() {
    var res string
    if protocol != "" { res += protocol + "://" }
    if user != "" { res += user + "@" }
    res += host
    if port > 0 { res += ":" + port }
    if dir != "" { res += dir }
    // handle more stuff for URL
    return res
}

Having worked in the proxy land for some time we've had some success with decomposition of types that seem simple at first.

---

_blueprints/work_item_types.adoc, line 46 [r1] (raw file):

Previously, tsmaeder (Thomas Mäder) wrote…

A reference to a work item...not sure if this needs to be typed yet.

okay

---

_blueprints/work_item_types.adoc, line 50 [r1] (raw file):

Previously, tsmaeder (Thomas Mäder) wrote…

Why is the ordering important and how will it be achieved or can it be influenced by the user? Will a string list always be sorted in alphanumerical order?

We will preserve the order given by the client. Sorting is a derived property and does not need to be specified in the type.

What about lists of user-defined types?

Nope, trying to keep it simple.

What about a map collection?

What's the use case?

What about a set? This could be extremely helpful for membership relationships.

Actually, it's not as useful as it sounds. Because we are useing a read/save model, the client would have to make sure it's not sending duplicates, otherwise the "save" operation would be rejected. So all we can add here is a level of safety.
In general, I don't think offering multiple collection types will help us validate the proposed concept. I propose we try to get a simple model right first and add variations later.

I fear this going in the wrong direction. Sadly I cannot tell you more about it (NDA :( ) but when defining another language with types and everything we originally went with lists and maps of only predefined types. This was re-written shortly after we went into using our own model.

A use case for a map could be a user-defined voting type with for polls. The question (key part) could be a string and the number of votes (value part) for each question could be an int.

---

_blueprints/work_item_types.adoc, line 52 [r1] (raw file):

Previously, tsmaeder (Thomas Mäder) wrote…

What's wrong with it?

I think this is better: An `enum` type holds one value out of a set of values of predefined types.

---

_blueprints/work_item_types.adoc, line 56 [r1] (raw file):

Previously, tsmaeder (Thomas Mäder) wrote…

Project == the configuration point for work process/work item types.
It's essential to the idea of duck typing in queries..."type like X" can be compiled to "type in (a, b, c)". If you have millions of types, that doesn't scale.

I don't say I fully understand this but I go with it :)

---

_blueprints/work_item_types.adoc, line 60 [r1] (raw file):

Previously, tsmaeder (Thomas Mäder) wrote…

Because we want the ecosystem to reuse their respective work. If there is a "hours worked" field, I want other plugins (for example on to repor to a time trackign system) to reuse that field name and not define their own.

I think people will naturally do that. But I think there's a trade-off : On the one hand side there the need for re-use of existing fields. On the other hand with every "special" field like `hours_worked` we introduce some code somewhere that is just dealing with this field only.

I say, the more general we can keep the system the more re-usable parts will be there.

Plus we should make sure that we provide some of the key-extensions for time tracking for instance and make the documentation that good so no one is willing to invest the time to reinvent the wheel.

If we keep default extensions to a minimum people will do crazy stuff and not share back their extensions in a good way, being too big or too specific. If we show them how to do small things very clean and organized they will eventually do the same, don't you think?

---

_blueprints/work_item_types.adoc, line 61 [r1] (raw file):

Previously, tsmaeder (Thomas Mäder) wrote…

I disagree...by reusing the "owner" field, we say: "this is the same field". It's not just that it has the same name by chance. Plugins (or services, or whatever) in a certain domain should agree on a common vocabulary.

Yes, I'm with you. Plugins **should** agree on this but we shouldn't be more clever than we actually can be. We know that know we know nothing too me sound the better hypothesis.

Just take the words sprint and iteration; both essentially mean the same things to some extend but we shouldn't be the ones to make this decision. Sooner or later there will be types where we cannot be clever and that's when we need to have a GUI that let's a user/admin wire up things.

Maybe there are even times when the GUI uses the same words (maybe due to internationalization) but they have totally different names in English. Can the user expect us to be clever with names here? Sure he cannot because to us the names are different.

---

_blueprints/work_item_types.adoc, line 72 [r1] (raw file):

Previously, tsmaeder (Thomas Mäder) wrote…

I'm not proposing multiple inheritance (outside of mixins). Shipping with predefined types ensures minimal content for all kinds of work items.

Like I said I'm in favor of the idea to have a standard set of extension / plugins available maybe but even those standard types need to be extensions.

---

_blueprints/work_item_types.adoc, line 78 [r1] (raw file):
I just think this paragraph needs some clarification and when you explain something like

Concretely, any work item type that includes the same structure as the queried for type will match.

I think we should specify more what duck typing is (which is what I tried). Maybe as a side node. But it helps the reader understand better. If I were to write something about JavaScript prototypes without telling what the difference to OO is then I cannot expect a C++ or Java Programmer to follow.

So my intention wasn't to be formal but have a more concrete example than yours.

---

Comments from Reviewable

[tsmaeder]

Review status: all files reviewed at latest revision, 22 unresolved discussions, some commit checks failed.

---

_blueprints/work_item_types.adoc, line 41 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

Feel free to share your experiences and what what particular torture awaited you in imlicit conversion hell.

I suggest to have these types of constructors

func NewURL(u string) (URLType, error)
func NewBoolean(b string) (BooleanType, error)
func NewDuration(uint64 a, uint64 b) (DurationType, error)

and maybe have each type implement a common interface to convert to standard types

type ToString interface {
    func ToString() string
}

// A URL stores all parts of a unified resource location in separated parts
type URL struct {
    protocol string
    user string
    host string
    port uint64
    dir string
    // ...
}

func NewURL(u string) (URL, error) {
    // Decompose from u into part of URL and return
    // ...
}

// ToString returns a string representation of a URL object
func (u URL) ToString() {
    var res string
    if protocol != "" { res += protocol + "://" }
    if user != "" { res += user + "@" }
    res += host
    if port > 0 { res += ":" + port }
    if dir != "" { res += dir }
    // handle more stuff for URL
    return res
}

Having worked in the proxy land for some time we've had some success with decomposition of types that seem simple at first.

I still don't see where the hurt is.

---

_blueprints/work_item_types.adoc, line 50 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

I fear this going in the wrong direction. Sadly I cannot tell you more about it (NDA :( ) but when defining another language with types and everything we originally went with lists and maps of only predefined types. This was re-written shortly after we went into using our own model.

A use case for a map could be a user-defined voting type with for polls. The question (key part) could be a string and the number of votes (value part) for each question could be an int.

But I am NOT defining a general purpose language...I am defining an object model for storing and retrieving work items.

---

_blueprints/work_item_types.adoc, line 60 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

I think people will naturally do that. But I think there's a trade-off : On the one hand side there the need for re-use of existing fields. On the other hand with every "special" field like hours_worked we introduce some code somewhere that is just dealing with this field only.

I say, the more general we can keep the system the more re-usable parts will be there.

Plus we should make sure that we provide some of the key-extensions for time tracking for instance and make the documentation that good so no one is willing to invest the time to reinvent the wheel.

If we keep default extensions to a minimum people will do crazy stuff and not share back their extensions in a good way, being too big or too specific. If we show them how to do small things very clean and organized they will eventually do the same, don't you think?

I don't think I'm making myself clear here...conceptually, there are no special fields (except what's needed to store work items). We're just fostering reuse by publishing names and types of often used fields.

---

_blueprints/work_item_types.adoc, line 61 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

Yes, I'm with you. Plugins should agree on this but we shouldn't be more clever than we actually can be. We know that know we know nothing too me sound the better hypothesis.

Just take the words sprint and iteration; both essentially mean the same things to some extend but we shouldn't be the ones to make this decision. Sooner or later there will be types where we cannot be clever and that's when we need to have a GUI that let's a user/admin wire up things.

Maybe there are even times when the GUI uses the same words (maybe due to internationalization) but they have totally different names in English. Can the user expect us to be clever with names here? Sure he cannot because to us the names are different.

All I am saying is that when you use the same field identifier, you need to use the same type. I don't care one bit how it's presented to the user or what the semantics are.

---

_blueprints/work_item_types.adoc, line 72 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

Like I said I'm in favor of the idea to have a standard set of extension / plugins available maybe but even those standard types need to be extensions.

They are...conceptually it's turtles all the way down.

---

Comments from Reviewable

[kwk]

Review status: all files reviewed at latest revision, 17 unresolved discussions, some commit checks failed.

---

_blueprints/work_item_types.adoc, line 41 [r1] (raw file):

Previously, tsmaeder (Thomas Mäder) wrote…

I still don't see where the hurt is.

You asked for sharing my experience and I've shared a code sketch (with errors, yes). I cannot tell you what problem was back then because of the NDA. With my code I don't think we will run into the problems that we had. That's what I wanted to tell. Nothing more. There's no hurt if we agree that there potentially could be an implicit conversion hell.

---

_blueprints/work_item_types.adoc, line 50 [r1] (raw file):

Previously, tsmaeder (Thomas Mäder) wrote…

But I am NOT defining a general purpose language...I am defining an object model for storing and retrieving work items.

We weren't defining a general purpose language either.

---

_blueprints/work_item_types.adoc, line 60 [r1] (raw file):

Previously, tsmaeder (Thomas Mäder) wrote…

I don't think I'm making myself clear here...conceptually, there are no special fields (except what's needed to store work items). We're just fostering reuse by publishing names and types of often used fields.

Good. Then hopefully we mean the same.

---

_blueprints/work_item_types.adoc, line 61 [r1] (raw file):

Previously, tsmaeder (Thomas Mäder) wrote…

All I am saying is that when you use the same field identifier, you need to use the same type. I don't care one bit how it's presented to the user or what the semantics are.

Okay. Is it technically possible to have two WorkItemTypes each with the same field identifier inside?

---

Comments from Reviewable

[tsmaeder]

Review status: all files reviewed at latest revision, 17 unresolved discussions, some commit checks failed.

---

_blueprints/work_item_types.adoc, line 61 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

Okay. Is it technically possible to have two WorkItemTypes each with the same field identifier inside?

yes, as long as they are compatible

---

Comments from Reviewable

[tsmaeder]

Review status: 0 of 1 files reviewed at latest revision, 17 unresolved discussions.

---

_blueprints/work_item_types.adoc, line 8 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

json

should be

JSON

fixed

---

_blueprints/work_item_types.adoc, line 36 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

I learned that Goa does have something for this already. See the Attribute API docs: https://goa.design/reference/goa/design/apidsl/#func-attribute-a-name-apidsl-attribute-a

This looks like the possibility to add arbitrary complex validations (that don't required DB access or something) in the design:

Attribute("name", Integer, "description", func() {
    Enum(1, 2)                  // And validation rules
})

Yes, but since 99% of our fields are described by work item types, not Goa, it will not generally address validation.

---

_blueprints/work_item_types.adoc, line 69 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

like

is not needed because you continue with (think [...])

fixed

---

Comments from Reviewable

[kwk]

Reviewed 1 of 1 files at r2.
Review status: all files reviewed at latest revision, 12 unresolved discussions, some commit checks failed.

---

Comments from Reviewable

[tsmaeder]

Review status: all files reviewed at latest revision, 12 unresolved discussions, some commit checks failed.

---

_blueprints/work_item_types.adoc, line 23 [r1] (raw file):

Previously, kwk (Konrad Kleine) wrote…

They are no ascii double quotes but angled double quotes and that makes them problematic.

Why are typographic quotes a problem? Shouldn't this be unicode?

---

Comments from Reviewable

[maxandersen]

this pr seem stale - is the doc ready to be merged in or still things active ?

[alexeykazakov]

Closing as outdated.

[kwk]

Closing as outdated.

@alexeykazakov please not just close this as outdated. In the current situation that we're in, I find this old document with a vision quite interesting to read again. Maybe it can actually help us. I'm reopening it for the sake of a proper documentation. This obviously is outdated, yes, but not close-able IMHO.