The current roadmap is for 2022 https://cdevents.dev/community/roadmap/.
We should update it to 2023/2024 and add items we are working on.

As discussed during the CDEvents WG on Jan 24th, 2023, it would be beneficial to expand the versioning documentation in the primer.md to include the reason behind the current approach, specifically what are the benefits of including the event version number into the event type.

When folks want to come and check out what CDEvents is, it is a harder concept to fully understand, and attending the meetings is important for questions, etc.

Going to the https://cdevents.dev/community/ it is not obvious where to register/sign up for the community meeting and see what time it is on, therefore I propose we make it more easier to find and have a proper link on the page.

I am seeing a potential conflict between Docsy and GitHub Markdown with relation to images in the spec documents.

I am using a much more recent version of Hugo for my local testing and have been seeing the following problem, which is not currently visible on the live site.

Using primer.md as an example:

The document makes reference to images that are located in an images folder, parallel to the referencing document in the spec repo. These use relative addresses in Markdown links of the form images/image-name.svg.

When viewed in GitHub, the relative address correctly maps to the required image.

In the cdevents.dev repo, the images folder is mapped to an absolute URL of 'https://cdevents.dev/docs/images/'.

Under Hugo, the primer.md file is mapped to an absolute URL of 'https://cdevents.dev/docs/primer/'

On the deployed version of Hugo, relative requests to images appear to get mapped to 'https://cdevents.dev/images/image-name.svg', which looks like a bug in Hugo, because this is what you would expect from absolute addresses with a leading /. Since there is no image folder in this path, some smart reconciliation must be going on because the images are found successfully, somehow.

On my local copy of Hugo, v0.106, however, the behaviour is different. Relative address lookups are now mapped to an absolute URL of 'https://test.host/docs/primer/images/image-name.svg', which is correct, relative to the Hugo path of the document making the relative address. This means that images are not being found in my test environment.

Images can be successfully opened at an absolute URL of 'https://test.host/docs/images/image-name.svg', which is where you expect them to be mapped. We could modify the original links to point to /docs/images/image-name.svg and they would be found under Hugo, but then would not be visible inline on the documents on GitHub.

There are image path reconciliation tools in Hugo, but these only work if you use the imgproc shortcode to declare the image in markdown, so won't work on GitHub.

We need to have a plan for addressing this, as it will break the site when Hugo is upgraded.

The Slack invitation link is using the channel URL instead of the invitation URL.

When you click on it and you have not joined the CDF slack, there's no way to sign up because it's email domain restricted.

I think it should be https://join.slack.com/t/cdeliveryfdn/shared_invite/zt-nwc0jjd0-G65oEpv5ynFfPD5oOX5Ogg per https://cd.foundation/community/.

We should clearly describe what version of the spec the documentation describes. Preferably enabling to select the wanted version through a drop-down list or similar.

The website uses the docsy hugo theme to host the content for the spec under https://cdevents.dev/docs.
The content of the spec is pulled into the website repo via git submodule.

The IDs of JSON schemas in the spec are in the format "$id": "https://cdevents.dev/draft/schema/artifact-packaged-event",.
We need to make sure that the URLs embedded in the schemas resolve to the actual schema, so that we may use that URL in CDEvents and CDEvents clients may fetch the schema from the URL.

Versions of the cdevents.dev narrative content in other languages can be added at any time by adding a new, language-specific content root under the content folder in this repo and providing translated duplicates of the files found in content/en.

The [languages] section of config.toml should be updated as documented in https://www.docsy.dev/docs/language/

UI strings are maintained in the i18n folder. You may need to update these if the desired language is not already supported.

In development, run hugo server --printI18nWarnings when doing translation work, as it will give you warnings on what strings are missing.

Translations of the specification documentation will require language-specific forks of the spec repo. The docs subfolder of the content/<new language>/ folder should be linked as a git submodule to the appropriate fork. Note the need to manually maintain and synchronise the releases of translated versions of the spec.

Audience Personas

When writing content for cdevents.dev, it is important to understand who this site is intended to serve and to ensure that the needs of each group are being addressed with appropriate information.

We anticipate that the primary audiences for this site are:

• CI/CD Tool Maintainers (Vendors / FOSS project members)
• Decision-makers, evaluating CI/CD tooling
• End-Customer Engineers, implementing CI/CD instances
• Browsing audience, looking to understand more about best practice

Let's understand the needs of each group in more detail.

CI/CD Tool Maintainers

As a CI/CD Tool Maintainer, I work for a commercial CI/CD Tool Vendor, or am a contributor to a FOSS project that maintains a CI/CD tool.

I am highly technical and understand the benefits of standardization and interoperability.

My primary interest is in understanding the specification so that I can implement functionality in my product correctly.

I may be a producer of events who is maintaining a CI/CD platform tool, or I may be a consumer of events who maintains an associated CI/CD product such as a metrics collection system or visualizer.

Decision-makers

I work at an End-Customer organization and am currently evaluating CI/CD tooling options in order to support our transition to Continuous Delivery.

I may come from a technical or a commercial background and am at an early stage of familiarity with the challenges associated with Continuous Delivery.

I need help to understand how best to differentiate between all the tooling options available to me.

End-Customer Engineers

I work at an End-Customer organization and am responsible for implementing our internal CI/CD instances.

I am technical and understand some of the challenges in the Continuous Delivery space but want to learn more about how CDEvents make my life easier.

Browsing audience

I am interested in CI/CD and Continuous Delivery and am looking to understand more about best practice in this space.

I have been reading the CDF Best Practices Guide and was referred here from there. I may be more or less technical in background and would like to understand where the value in CDEvents lies for me.

Audience Strategy

By looking at our personas, we can see that we have two basic narrative tracks that we must cater for:

• There is a highly technical audience that needs very detailed and accurate specifications
• The remainder of the audience remains to be convinced and will need a story that they can follow to their satisfaction

CI/CD Tool Maintainers and a large proportion of the End-Customer Engineers will want to approach the site as reference documentation. For this audience, we need clear links that take them immediately to the detail, structured in such a way that they can find what they need, but also have visibility of the full scope of the information available, to help them to size the effort facing them.

The intent is for this audience to have a pleasant experience, implementing CDEvents.

Decision-makers and the browsing audience are likely not bought into the content upon first arrival, so we have perhaps ten to twenty seconds to persuade them to invest more time in order to learn what is of value to them in the content. This requires a succinct and friendly landing page that pitches a clear message above the fold. This should then expand into a non-technical narrative providing the basic concepts before leading into the detail, with the expectation that few from this audience will consume all of the information themselves.

The intent is for this audience to take away key learnings that they will use to support future decisions, and to direct others to visit to access the details.

It is additionally expected that some CI/CD Tool Maintainers and End-Customer Engineers will benefit from the conceptual narrative that will enable them to easily become evangelists for the CDEvents approach. CI/CD Tool Maintainers may need help in communicating to their own customers the value-add of CDEvents support in their systems. End-Customer Engineers are often in a situation where they have to pitch a technology to their Decision-makers to get buy-in for a given approach, so simple explanations of commercial value can be very helpful to this audience.

This strategy must extend beyond the learning journey into the community space. Once we have explained the specification to the CI/CD Tool Maintainers, this must be reinforced with a call to action to implement the spec within their product and connection to appropriate additional support and community resources to help make this as easy as possible.

For all of our audience, we would additionally like to create a call to action to become contributors themselves and to add to the shared value.

I received a few times the feedback that the information about adopting tools and supporting companies should be made available and relevant on the CDEvents website.

I think this is a great idea - for the companies we may want to get a review from involved parties before merging the associated PR.

The schema links are not copied to https://cdevents.dev/0.4.0/schema/
which is resulting a failure while validating CDEvents against schema,

[main] ERROR com.networknt.schema.JsonSchemaFactory - Failed to load json schema from https://cdevents.dev/0.4.0/schema/links/embeddedlinksarray.json
java.io.FileNotFoundException: https://cdevents.dev/0.4.0/schema/links/embeddedlinksarray.json

The project website cdevents.dev has been created by me in a day or two, and it could benefit from an expert refresh, to ensure standard accessibility guidelines are followed, colour palettes are in order, relevant information (community, slack, spec) is easy to discover and finally, that the content is written in a good and clear style.

As part of the cdevents.dev refresh, we need to document the desired process for managing publication of spec revisions.

This has two main drivers:

1. We need to understand the release process well enough to identify any issues that might arise that would shape the requirements for the website itself.

2. We should publish the process itself on the website, both for transparency, and to ensure that it is easy to repeat the process consistently and reliably over time, with new contributors.

This requires a conversation over the next 1-2 weeks to ensure that we have enough information to support the completion of the website refresh.

This listing lacks the new bucket "Continuous Operations Events": https://cdevents.dev/docs/

That bucket was introduced through this PR: cdevents/spec#107

If we are going to change the look and feel of the site, we will need to make local changes to docsy themes. Since you have docsy installed as a submodule, can I suggest that you sync this module with upstream so that you have the latest image before we start to make changes?

Consensus is needed on the expected target devices which should be compatible with cdevents.dev

Of particular interest is what expectations are about rendering the spec in a readable form on small devices like phones?

The primary user journey requires that we engage the reader's attention with a succinct statement of value to them on the landing page, then provide an easily navigated narrative that evidences this statement, leading into the detailed content of the specification itself. It is expected that readers will self-pace, exiting the site when they have consumed sufficient detail for their needs.

We should, therefore, provide access to community resources from each page, to allow people to connect with additional support at whatever level of detail suits their needs.

For our technical narrative track, it must be obvious how to reach the reference section of the site directly from the landing page, allowing this audience to get quickly to the detail that they require.

The specification must be unambiguous, minimizing opportunities for multiple interpretations to hold true.

It must be obvious which version of the specification is referenced in the documentation and difficult to accidentally navigate between different versions whilst browsing. The specification should therefore be sandboxed within a consistent namespace so that relative links remain within the same version by default.

The default behavior should be to direct the reader to the latest version of the specification. Links should be provided to the specification GitHub repo to access historical releases of the spec.

The landing page shall present the key statement of value and a shortcut to the reference documentation above the fold. The remainder of the narrative introduction should sit below this on the same page, with jumping off points to details. Where detail sits within the specification or other versioned reference documentation, the landing page should always reference the latest version of these resources.

The user experience should strive for simplicity, consistency and coherency. As a reference work, it should be possible to navigate forwards and backwards through the site in a predictable manner without being redirected to an unexpected point in the content.

Active page elements such as pop-ups should be avoided. There is no requirement to collect data from the reader, nor to embed advertising or promotions within the site.