Page MenuHomePhabricator

[Task] Put sources of datamodel diagrams into the respective code repositories
Closed, InvalidPublic1 Estimated Story Points


UML diagrams should be put into the respective repositories in an editable format.

Event Timeline

Tobi_WMDE_SW raised the priority of this task from to Medium.
Tobi_WMDE_SW updated the task description. (Show Details)

Please specify which diagrams should be uploaded into which repositories. (Just pointing at that diagrams should be fully approved *before* submitting a pull request / commit.)

These should be the most recent versions of the diagrams I compiled. (Entityview diagram is supposed to be work in progress and it does not look like it will be finished.) You probably want to rename the files before uploading.

@Lydia_Pintscher @daniel Here are the sources of the diagrams. Feel free to put them into the respective repositories. The high-level diagram should probably not go into a repository but into the wiki together with e.g. the data model primer.

If you feel the unnecessary need for attribution when uploading, just suppress it; At least, just do not use any full name. Thanks. If something is to be uploaded to commons, I could do that with my account as well.

@Tobi_WMDE_SW Wikimedia allows only a limited set of file formats for upload. We cannot upload MDJ files. We could embed the XML in a wikitext page, but that's super ugly. We can and should upload SVG or PNG renderings of the diagrams, of course.

For now I suggest to put the sources of the high level diagram into the docs/ directory in Wikibase.git. If we end up having a lot of abstract documentation like that, a separate git repo might be justified.

We should however also decide which file format we want to use. MDJ is StartUML's format, which (I assume) is open and documented, but can it be read by other UML software? The "official" exchange formats for UML seem to be UXF and XMI. But I don't know how well supported these are in reality....

I would be especially interested in a format that works with a Free Software, which AFAIK StartUML is not.

Yay for agile documentation!

One concern I do have is that if we bundle a diagram with the code, then it needs to be updated when the code is updated. Not for every commit clearly, but for every release that includes significant changes. So it'd be good if multiple people can do this updating, else we introduce a potential release blocker (of course we could always drop the diagram in such a case, but that is clearly not ideal either).

How do you want to move on with that? The files as they are now can be exported to either PNG, JPEG, SVG or PDF using StarUML. It is not possible to export these to UXF or XMI. If it is a strong requirement to have these files in one of these formats, that AFAIK would mean to redo them. In that case it is currently unclear what priority this has and when there will be free capacities to do this work.
In short:

  • please either put the mdj files into the respective repositories or specify which of the possible export-formats (PNG, JPEG, SVG, PDF) you want to have.
  • if this is not possible and the diagrams need to be redone, then block this task on a new task "Redo UML diagrams in format <desired_format>" and then remove the task from the sprint.

If we can't get UXF or XMI, I suggest to put SVG on commons, and MDJ into git (not sure which repo, though). On the description page of the SVGs, there should be a link to the file in the gerrit repo, and instructions for checking it out and in. Direct modification of the SVG should be avoided. It's annoying though that StarUML would be required for editing.

Please lets find a free software tool that we can work with. Otherwise we will not be able to properly update the diagram.

I have used this before:
Open source, free, not sure what file formats it can output etc

Decision during sprint start: if the SVG is editable, put them on Commons and be done

Jonas renamed this task from Put sources of datamodel diagrams into the respective code repositories to [Task] Put sources of datamodel diagrams into the respective code repositories.Aug 13 2015, 7:26 PM

Outdated, we are leaving T75604 to cover this, it may one day be re-evaluated.