Replace server_id with human_readable_id, make it creatable by clients

[lasselindqvist]

This is opened due to #201

I feel like the addition requires two changes:

1. Rename the server_id to human_readable_id, since server_id isn't really representing the meaning of the field too well
2. Allow the field to be generated by clients.

It seems that the intention currently is to let the BCF server web UI users to generate these IDs, since the examples do show some context in the example IDs that requires human input. But in my opinion the web UIs should be treated as clients to the server as well.

It would be useful if software such as Solibri could generate the IDs already upon topic creation, since Solibri does have the context for the topics available. It knows if the issue relates to a clash and can name it CLASH-1234. The problem here might be that the client software has a hard time knowing which number is available for given context word. Client could have retry logic increasing the number if the previous is taken, or another possibility is that the BCF API does not allow the clients to generate the ID, but does allow them to pass on the context word for the server and the server then assigns a free number to follow it. But this approach somewhat assumes that all users want to use format WORD-NUMBER.

[ykulbak]

@lasselindqvist I don't feel strongly about field's name. As explained in #201, most issue servers already provide a mandatory, server controlled, project-unique and user friendly issue identifiers - this feature is a simple extension of BCF to expose that. Issue servers mostly don't allow their user friendly ID to be specified by users - the IDs are auto generated to guarantee consistency and uniqueness. Some servers support an ID generation scheme but this is beyond the scope of BCF which focuses on interoperability.

[lasselindqvist]

I guess this thought I have could be achieved with pre-existing labels as well.
I am specifically thinking about this example here https://github.com/buildingSMART/BCF-API/pull/206/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R731
How does the server know to call that topic a clash? If server just blindly generates the IDs as ISSUE-1234 incrementing the integer, it makes sense to just have the field as server generated immutable. but if the server can call some topic CLASH-1234, how does it make that decision? Now, I don't know how these decision are made, perhaps based on existing labels? If that is the case, the client can achieve this by just making sure the necessary label exists upon topic creation.

Of course if the decision in the server is based on labels, it is likely different for each server, and the client could not rely on that behavior if it wanted "nice" IDs to be generated.

[ykulbak]

Not all issues are created through BCF - some issues are created within a single vendor's ecosystem. Other issues may be created via a combination of BCF and vendor-specific agreements.

The Server ID generation scheme is not in the scope of the BCF specification. In practice, all servers generate user friendly IDs today and this feature would allow BCF clients to present the IDs to users.

[ykulbak]

Discussed in the open CDE Hackathon and decided the following:

1. server_id is ambiguous and should be renamed to server_assigned_id
2. Clients should not be allowed to set this value
3. Change the example to remove / change 'CLASH' to a clearer value

[jasollien]

#249

[ykulbak]

Closed by #249