ossuminc / riddl Goto Github PK

Bounded Contexts are very isolated from other constructs. To speed up validation, AST.Context instances could be processed in parallel during validation without harm. The message list will need to become thread safe but there should be little other impact than that.

Install RIDDL binaries to a user's machine and configure environment variables to get the user operating with riddl quickly.

What was in the docs and what was accepted by the validator were vastly different. Too many errors to document here.

┆Issue is synchronized with this Jira Story by Unito

This is a request to create a new section in the hugo translator's output that organizes information focusing on message types, how they are used, where they are defined, and where in the hierarchy they exist.

Message types are the four DDD types: command, event, query, and result. The documentation for every leaf subdomain should have four pages added, one for each kind of message type. Those pages should list all the messages of their type that are USED by the subdomain (all contexts) but none that are merely accessible by the subdomain. Ideally, that wouldn't happen, but in practice, it will.

Each page contains a list of relevant messages. Each row in that list starts with the name of the message and then a set of tabs:

• Type - shows the fields of the message, with their brief descriptions if any
• Defined In - shows the subdomain, context, entity, or other definition in which the message is defined, along with that definition's brief description
• Used In - shows the places from which this message is used with full path identification, and each path component is a link to the documentation for that definition.
• Description - Full description of the message as defined in its "described by" type which could be fairly involved with diagrams, etc.

Syntax should be:
type DoIt is command {}
type DidIt is event {}

┆Issue is synchronized with this Jira Story by Unito

This blog:
https://rafaelritter.medium.com/ddd-model-integrity-patterns-36d0e8ac9561
has some good points that should be mentioned in practitioners documentation as best practices, etc.

Interaction was meant to capture an sequence diagram as an interaction between system components as an example of processing, but they are not definitional of even typical processing and therefore more a documentation tool than a system specification.

Sequence diagrams should be generated from definitions made in RIDDL, not the other way around.

Consequently, Interactions should not be part of the language.

Autocompletion works when typing in a reference of any kind. Since RIDDL prefixes such references with a keyword (type, entity, etc.), only the matching identifiers for that kind of definition will be shown. Upon completion, the shortest identifier path to the selected identifier will be inserted.

https://gitlab.com/yoppworks/ossum/riddl-idea-plugin/-/blob/main/img/autocompletion.gif

┆Issue is synchronized with this Jira Story by Unito

James has a document on Google Docs that should be factored into the documentation

The first instance has content. The second does not.

Text entered into RIDDL files that is not syntactically or referentially correct will be highlighted with squiggly red underlines as is common for programming languages.

┆Issue is synchronized with this Jira Story by Unito

How do these UML Sequence Diagrams get generated. We know that the answer lies in Hugo/Mermaid, but the documentation will need to help the user understand how to accomplish this.

┆Issue is synchronized with this Jira Story by Unito

┆Issue is synchronized with this Jira Story by Unito

The left navigation pane currently scrolls together with the main body of the topic you are currently viewing. For example if you navigate to Language -> Conventions you will find that the conventions content is larger than your current screen. If you want to maybe navigate to another topic you cannot scroll to that topic in the navigation pane without scrolling the whole page, losing context of what you were just reading. These two things should be independently scrollable.

┆Issue is synchronized with this Jira Story by Unito

This action, when invoked upon any identifier, looks for all usages of that identifier in the project (not just the current root domain). Usages include identical occurrences of the identifier in strings and comments.

┆Issue is synchronized with this Jira Story by Unito

• Rename: FormatTranslator → ReformatTranslator
• Base it on a Folding function, not Folding Trait (avoid inheritance)
• Make “Include” be honored and implement both sides of “single-file” option

Install RIDDL binaries to a user's machine and configure environment variables to get the user operating with riddl quickly.

Should we add a glossary language component where we can declare a term and provide a definition? This would be useful in establishing the Ubiquitous Language within a bounded context or domain. If, elsewhere in the spec (maybe a described as block) if a glossary term is used and annotated the output could generate a link to that definition.

A glossary term must be defined within a hierarchy. A term defined within a bounded context or domain has no relevance or meaning outside of the scope where it was defined. If you are in a subdomain the glossary terms of the parent domain still apply - unless expressly overridden. Other relationships (child, sibling) could explicitly reference a definition using that relationship, under the condition that the term is always referenced and cannot be altered unless done where the term was defined.

Any tasks having to do with the doc and examples sections of RIDDL

┆Issue is synchronized with this Jira Epic by Unito

When creating a RIDDL specification it may be useful to link a user to another part of the specification. This could be done with a See Also declaration.

This change implies revision of the FormatTranslator and Validator to use the simpler foldLeft definition and without using a Folding trait subclass. This makes traversal more flexible and functional.

┆Issue is synchronized with this Jira Story by Unito

I am going through the detail of adding definitions for each type, entity, context, domain, command/event/query/result, etc. in a RIDDL file. It made me think, this would be a tremendous opportunity to get users from the business and others involved in the definition of the domain model. It would offload a lot of work from the RIDDL author, and it would serve to get buy in from the true owners of the model.

This is certainly a down the road OSSUM feature. But I think we may need to give some thought on how we could simplify the RIDDL syntax to accommodate this. For example, you declare a new domain as potentially the very first thing in the RIDDL file, however, because of syntax you have to scroll to the end (of a potentially large file) of the file in order to reach a point where you can actually define it. One thing that might ease things a bit on this point is extending the IntelliJ plugin to allow you to collapse blocks of code? Allowing us to include definition blocks outside of the actual RIDDL file (which we have discussed previously) may also help.

A nifty integration for this would be if the validator noticed that something was missing a definition, rather than throwing an error create a JIRA (plug in task management system here) ticket to capture the work. It would be fantastic if the (future) OSSUM feature would allow a conversation (comments/replies) around defined by sections.

It would be handy to include all these defined by blocks in a glossary output - maybe as part of the Hugo site.

Anyway, capturing a thought. Maybe we can discuss further in the future.

I am getting a lot of name conflict warnings with my RIDDL file. Here is the thing, however, I only see it as a conflict within the RIDDL file, but not in actual implementation because the definitions are context sensitive. Here is an example:

[warning] Style: projectx.riddl(249:53): Field 'retailerId' overloads:
Field 'retailerId' at projectx.riddl(66:21),
Field 'retailerId' at projectx.riddl(283:21),
Field 'retailerId' at projectx.riddl(240:21),
Field 'retailerId' at projectx.riddl(326:21),
Field 'retailerId' at projectx.riddl(253:67),
Field 'retailerId' at projectx.riddl(106:21),
Field 'retailerId' at projectx.riddl(257:21)

Each of these is used in either defining a state for another entity, or is an argument for a command/event. It would get noisy and tedious to define each of these uniquely, for example orderBaseRetailerId so that the name was unique across the entire file. This method of naming is a bit redundant because retailerId is used in the definition of the OrderBase state.

Not sure if I am making sense here, but happy to talk it through when it is convenient to do so.

Perhaps somewhere (with each page maybe?) in the HUGO output files we need to have a TODO section that would list tasks that need work. These could be included based on a TODO marker in the RIDDL file, or maybe even with a ??? definition. (multiple ways to mark a TODO to include in the output)

This action helps when navigating the hierarchy of definitions. It performs a depth first traversal of containers and definitions but not into the details of a definition.

https://gitlab.com/yoppworks/ossum/riddl-idea-plugin/-/blob/main/img/gotoprevnext.gif

┆Issue is synchronized with this Jira Story by Unito

I expected to see an example of a Command or a Query. Instead, it seems there is an example of an Entity definition with an "options" modifier

┆Issue is synchronized with this Jira Story by Unito

BackOffice and Corporate RIDDL code examples are missing from the examples pages. The RIDDL files exist for the content, they are just not linked properly.

┆Issue is synchronized with this Jira Story by Unito

For example, if you navigate to Language->Definitional Hierarchy-> Root it appears that Definitional Hierarchy is indented at the level of Interactions before it and Root below it. But there is a pipe in front of it to show navigation context. Styling, however, makes it appear that it is one level down in the hierarchy. Also, the same is true of Root.

┆Issue is synchronized with this Jira Story by Unito

When URLS and Path Identifiers are used in the model's documentation they should be converted into URLs in the generated documentation to the corresponding definition or site's location.

For example:

https://yoppworks.slack.com/archives/CSN8D062K/p1643682989256299

which looks like this:

!Screen Shot 2022-02-01 at 2.51.44 PM.PNG|width=672,height=221!

and has this in the pipeline log:

Checking out d9d9daaa as main...

Skipping Git submodules setup
Executing "step_script" stage of the job script
Using docker image sha256:d456c516012bd9badbc8c66c8d5261fc9c3f81d5f637eedaa43b574d43f71dd0 for yoppworks/gitlab-runner-sbt-scala:latest with digest yoppworks/gitlab-runner-sbt-scala@sha256:9801590af7653a9acd9c4ce734d7c5266bb486642c33b0f79a20aed5ab2fd1af ...
Runtime platform                                    arch=amd64 os=linux pid=6 revision=4b9e985a version=14.4.0
FATAL: Command sh not found.                       
Cleaning up project directory and file based variables
ERROR: Job failed: exit code 1

┆Issue is synchronized with this Jira Bug by Unito
┆Attachments: Screen Shot 2022-02-01 at 2.51.44 PM.PNG

This project has graduated from "nascent" to merely "early". In the spirit of Linus Torvalds "commit early, commit often", this task asks for https://riddl.tech/ to be hosted on Google Cloud as a single VM that:

• • every hour:
    *checks out riddl to a directory.

• cleans, packages and runs the test suite

• if successful, starts "hugo -D server" from the examples/target/translator/ReactiveBBQ.riddl

• makes ReactiveBBQ site (see above) available at riddl.yoppworks.com/examples/rbbq

• hosts the API docs generated from the last build at https://riddl.yoppworks.com/apidoc

• hosts the riddl hugo docs at https://riddl.yoppworks.com/doc

This can probably be done most easily by constructing a container that has nginx, git, sbt, scala compiler and a few other things in it.

Riddl is its own thing and not a subpart of ossum. When we get to ossum, it will be used, but isn’t logically contained within ossum. Since RIDDL is open source, it needs to be not tied to the idea of Ossum.

This also means the GitLab project should not be buried inside the GitLab Ossum group. It is correct on GitHub (Yoppworks/riddl)

The RIDDL files exist. In the restaurant domain there are several bounded contexts defined that need to somehow be represented in the documentation.

┆Issue is synchronized with this Jira Story by Unito

Currently a SAGA expects to be able to coordinate a complex transaction via async messaging to entities (exclusively). SAGAs may also need to coordinate a complex transaction via synchronous calls to external services.

If you have a type like:

type FooRef = reference to entity Foo
type Bar = { refs: FooRef+ }

then you may want to iterate over those references in an action, say, to tell each one of them something. This is worth modeling in RIDDL.

Sometimes RIDDL authors want to put a long explanation of a RIDDL definition into its own .md file. We need to support that option.

This will allow Hugo documentation to highlight riddl source code when used between triple backticks sections, like this:

```riddl
domain foo is { ??? }
```

┆Issue is synchronized with this Jira Story by Unito

Add a "shell" command that allows riddlc to be used interactively so that commands and options can be typed in to a prompt and executed that way.

This action causes the editor to pop up the RIDDL provided documentation for the selected identifier.

https://gitlab.com/yoppworks/ossum/riddl-idea-plugin/-/blob/main/img/quickdoc.png

┆Issue is synchronized with this Jira Story by Unito

The documentation generated by riddlc should create context map diagrams for each domain showing both the contained contexts and the ones they interact with

GeekDoc’s “Edit” button isn’t getting the right URL to allow editing. The Hugo Translator needs to set the source URL in each generated file.

I believe that this section is describing a situation in which we are employing the Focuser Pattern.

Create a binary file format, BAST, to store pre-compiled RIDDL specifications that can be imported into other models.

!Screen Shot 2022-02-18 at 11.39.40 AM.png|thumbnail!

Names that are longer than the space allocated to the left nav simply bleed over into the main body content. See attachment.

Install RIDDL binaries to a user's machine and configure environment variables to get the user operating with riddl quickly.

The use of Location objects in every AST construct is time-consuming and wastes memory allocations. A significant saving could be had if we:

• Replace "Location" with just a Long (offset in file)
• Calculate Location only when its needed (method on RiddleNode)
• Create nodes for input sources (also helps with reflection and

Unfortunately, this is a long, unforgiving, touches everything kind of change at this point, especially in test cases, but worth it in the long run. Without this, every successful parse is penalized for the utility in generating error messages that won't be utilized.

┆Issue is synchronized with this Jira Story by Unito

Comments are currently ignored by the scala whitespace parser by fastparse. We actually want to keep the comments, as an array of strings, so they may be put out by reformat or otherwise processed by any translator.

We need to:

• Add Comment(loc: Location, isSingleLine: Boolean, lines: Seq[String]) to AST
• Change the white space parser to capture both single line (//) and multi-line (/* */) comments
• Have these things ignored by most translators
• Have ReformatTranslator regurgitate them.

We should be able to author markdown files - or snippets of markdown as a standalone file and #include that file into the RIDDL source. It will make authoring, commenting, and managing those files easier.

┆Issue is synchronized with this Jira Story by Unito

The primary function of the glossary of terms is to have a quick reference to terms and their definitions. In the current presentation, the type and path columns take up so much real estate that it crowds the definition and makes it hard to read.

Here are a couple of ideas for how we might do this (these are not requirements, but rather ideas to consider)

1. assign an icon for each of the types (Context, Entity, Function, etc.), move the icon to the first column, and drop the Type text-based column.
2. move the path under the term in a smaller font; or, maybe make it a popup when you hover over the term. Both could work, but we aren't sure how to pull that off in MD format...

create JIRA Project
create Git Repo
Initialize project structure (Riddl, src, test, docs, etc.)
boilerplate RIDDL source file