Created FAQ.md #48
Created FAQ.md #48
Conversation
sarthaknimbalkar
changed the title
sarthaknimbalkar
changed the title
|
Please let me know if any updates are required. |
FAQ.md
Outdated
| --- | ||
|
|
||
| ### **Q: Are there any libraries or SDKs available for CDEvents?** | ||
| **A:** Yes, the community has developed several libraries and SDKs in various programming languages to facilitate the implementation of CDEvents. You can find these resources in our [GitHub repositories](https://github.com/cdevents/spec) or [Docs](https://cdevents.dev/docs/) or explore community-contributed projects. |
There was a problem hiding this comment.
I think it would be good to provide links to SDK repos, like https://github.com/cdevents/sdk-go, https://github.com/cdevents/sdk-java and https://github.com/cdevents/sdk-rust. We could also mention that more SDKs are being developed and that contributions are welcome
There was a problem hiding this comment.
Q: Are there any libraries or SDKs available for CDEvents?
A: Yes, the community has developed several libraries and SDKs in various programming languages to facilitate the implementation of CDEvents. Below are some of the available SDKs:
More SDKs are being developed, and contributions are welcome! You can find additional resources in our GitHub repositories or in the official documentation.
Would this work ?
|
Sure sir, |
|
@afrittoli Umm, Hiii 👋 |
FAQ.md
Outdated
| --- | ||
|
|
||
| ### **Q: How do CDEvents handle event metadata?** | ||
| **A:** CDEvents includes a metadata section in each event payload, containing information such as event type, source, timestamp, and unique identifiers. This metadata ensures that events can be properly tracked, filtered, and processed across different tools and systems. |
There was a problem hiding this comment.
Perhaps here you could refer to the context and include a link: https://github.com/cdevents/spec/blob/main/spec.md#cdevent-context
There was a problem hiding this comment.
Included the link
Q: How do CDEvents handle event metadata?
A: CDEvents includes a metadata section in each event payload, containing information such as event type, source, timestamp, and unique identifiers. This metadata ensures that events can be properly tracked, filtered, and processed across different tools and systems. You can learn more about the context and metadata in the CDEvent Context section of the specification.
FAQ.md
Outdated
|
|
||
| ## Implementation and Integration | ||
|
|
||
| ### **Q: How do I implement CDEvents in my CI/CD pipeline?** |
There was a problem hiding this comment.
This is a good start. We recently formed a working group to discuss exactly this question - I don't think we have a definite answer yet, but the points you mention here are something that people can surely keep in mind.
I think it would be good to point to the implementation-wg and mention the points below as a starting point.
There was a problem hiding this comment.
How about this ?
Q: How do I implement CDEvents in my CI/CD pipeline?
A: Implementing CDEvents involves several key steps, and while a definitive answer is still being discussed by the community's working group, the following points provide a good starting framework:
- Identify Integration Points: Determine where events are generated and consumed in your pipeline.
- Adopt the CDEvents Schema: Ensure that your tools emit and listen to events following the CDEvents specification.
- Use Existing Libraries: Leverage available SDKs or libraries to simplify implementation.
- Configure Event Transport: Set up the communication mechanism (e.g., HTTP, message broker) for event transmission.
- Test Integration: Validate that events are correctly emitted, received, and processed across your tools.
We encourage you to follow the discussions and contributions from the CDEvents Implementation Working Group as they continue to refine the best practices for implementation. Meanwhile, you can refer to our implementation guide for detailed steps and examples.
There was a problem hiding this comment.
Thank you for the updates.
FAQ.md
Outdated
| --- | ||
|
|
||
| ### **Q: Can CDEvents be integrated with popular CI/CD tools like Jenkins, GitLab CI, or GitHub Actions?** | ||
| **A:** Yes, CDEvents is designed to be tool-agnostic and can integrate with popular CI/CD tools. Integration can be achieved by configuring these tools to emit and consume CDEvents-compliant events. Some community-contributed plugins and extensions may already exist to facilitate this integration. Check out for [Jenkins](https://plugins.jenkins.io/cdevents/) and [Docs](https://cdevents.dev/docs/) for specific instructions and available resources. |
There was a problem hiding this comment.
We don't have a good reference to tools that implement CDEvents - I filed cdevents/cdevents.dev#49 about this.
In the meantime, please refer to https://cdevents.dev rather than https://cdevents.dev/docs here, as at least on the main page we have a list of logos of implementing tools.
It would be good if you could include Spinnaker, Testkube and Guac.sh with links here
There was a problem hiding this comment.
Added
Q: Can CDEvents be integrated with popular CI/CD tools like Jenkins, GitLab CI, or GitHub Actions?
A: Yes, CDEvents is designed to be tool-agnostic and can integrate with popular CI/CD tools. Integration can be achieved by configuring these tools to emit and consume CDEvents-compliant events. Some community-contributed plugins and extensions may already exist to facilitate this integration. For example, check out the CDEvents plugin for Jenkins.
Other tools like Spinnaker, Testkube, and Guac.sh are also integrating CDEvents. You can visit the CDEvents homepage for a full list of supported tools and their logos, as well as resources on how to get started with each.
FAQ.md
Outdated
| ### **Q: What are the best practices for implementing CDEvents?** | ||
| **A:** Best practices include: | ||
| - **Adhere to the Specification:** Ensure all events conform to the CDEvents schema. | ||
| - **Use Semantic Versioning:** Follow versioning guidelines to manage changes. |
There was a problem hiding this comment.
I'm not sure what this means in this context.
Spec and events are already versions, that's not something CDEvents adopters have to do
There was a problem hiding this comment.
You're right that in this context, semantic versioning might not be necessary for CDEvents adopters, as the spec and events are already versioned. The focus should be more on how adopters can effectively implement and manage CDEvents.
FAQ.md
Outdated
| ### **Q: What are the best practices for implementing CDEvents?** | ||
| **A:** Best practices include: | ||
| - **Adhere to the Specification:** Ensure all events conform to the CDEvents schema. | ||
| - **Use Semantic Versioning:** Follow versioning guidelines to manage changes. |
There was a problem hiding this comment.
I'm not sure what this means in this context.
Spec and events are already versions, that's not something CDEvents adopters have to do.
FAQ.md
Outdated
| 3. **Review and Feedback:** Engage with the community and maintainers for feedback and revisions. | ||
| 4. **Approval and Integration:** Once approved, the event type will be integrated into the CDEvents specification. | ||
|
|
||
| For more details, see our [event proposal guidelines](https://github.com/cdevents/spec/issues). |
There was a problem hiding this comment.
The link there does not include any event proposal guidelines. I would remove this line.
FAQ.md
Outdated
| ## Miscellaneous | ||
|
|
||
| ### **Q: Can CDEvents be used outside of Continuous Delivery?** | ||
| **A:** While CDEvents is specifically designed for Continuous Delivery scenarios, its flexible and standardized event structure can be adapted for related areas within the software development lifecycle, such as Continuous Integration, DevOps practices, and even broader IT operations workflows. |
There was a problem hiding this comment.
This answer is incorrect. Continuous integration is already part of CDEvents as is continuous operations.
With Continuous Delivery refers to https://github.com/cdfoundation/faq?tab=readme-ov-file#what-is-continuous-delivery-cd but in fact CDEvents already goes beyond that, defining events that span from issues, through SCM systems, CI/CD processes, deployments and monitoring.
There was a problem hiding this comment.
i've corrected it according to your feedback
check if this works out
Q: Can CDEvents be used outside of Continuous Delivery?
A: Yes, CDEvents is designed to cover a broad range of scenarios across the software development lifecycle, not just Continuous Delivery. In addition to CD, CDEvents also supports Continuous Integration, DevOps practices, and IT operations workflows. The specification defines events that span from issue tracking and source code management (SCM) to CI/CD processes, deployments, and even monitoring and observability. For more details on Continuous Delivery, refer to the CD Foundation FAQ.
FAQ.md
Outdated
| - **Major Updates:** Introduce breaking changes with clear migration paths and deprecation notices to allow users to update their implementations accordingly. | ||
| - **Deprecation Policy:** Deprecated features are announced well in advance, with support timelines to facilitate smooth transitions. | ||
|
|
||
| Detailed information is available in the [versioning and compatibility section](https://github.com/cdevents/spec/issues/43) of our documentation. |
There was a problem hiding this comment.
Wrong link: https://cdevents.dev/docs/primer/#versioning is the correct one
FAQ.md
Outdated
| **A:** Maintaining backward compatibility is a priority for CDEvents. When introducing changes: | ||
| - **Minor Updates:** Add new fields or event types without altering existing structures, ensuring existing integrations remain functional. | ||
| - **Major Updates:** Introduce breaking changes with clear migration paths and deprecation notices to allow users to update their implementations accordingly. | ||
| - **Deprecation Policy:** Deprecated features are announced well in advance, with support timelines to facilitate smooth transitions. |
There was a problem hiding this comment.
We don't have a deprecation policy in place yet, nor specific timelines documented for deprecation.
Detailed versioning information is available at https://cdevents.dev/docs/primer/#versioning.
On top of that, until we reach our 1.0, we may be doing breaking changes.
There was a problem hiding this comment.
Q: How does CDEvents handle backward compatibility?
A: Maintaining backward compatibility is important for CDEvents. When introducing changes:
- Minor Updates: New fields or event types may be added without breaking existing structures, ensuring that current integrations continue to work.
- Major Updates: Breaking changes may occur, especially before reaching version 1.0, and will be communicated clearly to users with guidance for migration.
- Versioning Before 1.0: Until we reach version 1.0, breaking changes may be introduced as the specification evolves. Users should be prepared for potential changes during this period.
For more details, see the versioning and compatibility section of our documentation.
This better ?
FAQ.md
Outdated
| --- | ||
|
|
||
| ### **Q: How does CDEvents handle large-scale event processing?** | ||
| **A:** CDEvents is designed to be scalable and can handle large volumes of events by leveraging robust event transport mechanisms like message brokers (e.g., Kafka, RabbitMQ) and distributed processing frameworks. Implementers should ensure their infrastructure is capable of managing the expected event load and implement best practices for event handling and processing. |
There was a problem hiding this comment.
We indeed have scalability in mind when defining CDEvents, but scalability considerations are not those you mentioned there. Things we did to provide scalability features:
- keep the events as small as possible
- provide a context that can be used to efficiently route / filter messages, without parsing the entire payload. Some of the fields from the context (like subject) are also available at CloudEvents level for even more efficient routing / filtering
- we also consider the case of large amount of events being stored in some kind of database. We introduced links to help efficiently and easily searching events that belong to a single workflow
There was a problem hiding this comment.
Got it,
Q: How does CDEvents handle large-scale event processing?
A: CDEvents is designed with scalability in mind. Key features that support large-scale event processing include:
- Compact Event Design: Events are kept as small as possible to minimize overhead and improve performance.
- Efficient Routing and Filtering: The event context includes fields (such as
subject) that can be used to efficiently route and filter events without parsing the entire payload. These fields are also available at the CloudEvents level, enabling even more efficient processing. - Efficient Workflow Search: CDEvents includes links to help efficiently search and retrieve events that belong to a specific workflow, supporting the storage and querying of large volumes of events.
While CDEvents provides the foundation for scalability, implementers should ensure their infrastructure (e.g., message brokers, databases) is capable of handling the expected event load based on their specific use case.
|
Hey @afrittoli , |
|
heyy @afrittoli, |
FAQ.md
Outdated
| 1. **Fidelity Investments**: The CDEvents project is key to enabling interoperability, which simplifies the Software Delivery Lifecycle (SDL) processes. Fidelity uses an event-driven architecture to achieve continuous compliance for apps delivered in a highly regulated environment. Their internal tool, the Fidelity Pipeline Library, offers reusable pipeline templates with event triggers, showcasing how CDEvents can enhance developer experience and feature velocity. | ||
|
|
||
| 2. **Ericsson**: Ericsson co-founded CDEvents to address the need for innovative and simplified software deployment in telecommunications. They have implemented CDEvents in their CI/CD pipelines, demonstrating its effectiveness in achieving interoperability and streamlining processes. | ||
|
|
||
| 3. **TestKube**: This Kubernetes-native testing framework has adopted CDEvents to improve feedback loops and quality-gated workflows within CI/CD pipelines. The integration of test events allows for better tracking and management of testing activities. |
There was a problem hiding this comment.
May I ask what is the source of this?
I don't think we should include statements about what companies do or do not do with CDEvents unless they are:
- either reviewed/provided by someone at the company
- or taken from some publicly available source
My recommendation would be for now to drop this question, and we can work on it on a separate PR.
Alternatively please only include links to publicly available documents or statements, such as the Fidelity end-user story.
There was a problem hiding this comment.
few of the sources through which i had the reference :
- https://cd.foundation/blog/2023/05/08/cdevents-real-world-adoption/
- https://cd.foundation/tag/ericsson/
- https://testkube.io/blog/testkube-joins-cd-foundation
but as you said we'll drop this question for now and focus on it later on
|
Thanks - the updates look good to me, see one more comment please. |
|
also can you please add hacktoberfest and hacktoberfest-accpeted label for this pr |
FAQ.md
Outdated
| @@ -0,0 +1,268 @@ | |||
| # Frequently Asked Questions (FAQ) | |||
|
|
|||
| Welcome to the **CDEvents FAQ**! This page provides answers to common questions about CDEvents. Whether you're new to CDEvents or looking to deepen your understanding, you'll find valuable information here. If you don't find the answer you're looking for, please refer to our [documentation](https://cdevents.dev/docs/), [whitepaper](https://cdevents.dev/docs/wpaper/), or explore relevant discussions on [GitHub](https://github.com/cdevents). | |||
There was a problem hiding this comment.
nit: One thing when writing docs is to not use contractions. So instead of you'll spell it out to you will.
There was a problem hiding this comment.
Ahhh okay
Did not know this
Will take care
FAQ.md
Outdated
| ## General Questions | ||
|
|
||
| ### **Q: What is CDEvents?** | ||
| **A:** CDEvents is an open specification for Continuous Delivery events, designed to promote interoperability between tools in the software production ecosystem. It standardizes the format of events across various phases of the software development lifecycle, enabling seamless communication and integration between different CI/CD tools. |
There was a problem hiding this comment.
I would probably change CI/CD tools to something like SDLC (software development life cycle) tools.
There was a problem hiding this comment.
Should I make the change throughout the doc?
FAQ.md
Outdated
| --- | ||
|
|
||
| ### **Q: How does CDEvents differ from other event specifications?** | ||
| **A:** Unlike proprietary event formats or tool-specific integrations, CDEvents is an open, vendor-neutral specification focused solely on Continuous Delivery events. It emphasizes interoperability, flexibility, and ease of adoption across diverse toolchains and environments. |
There was a problem hiding this comment.
| **A:** Unlike proprietary event formats or tool-specific integrations, CDEvents is an open, vendor-neutral specification focused solely on Continuous Delivery events. It emphasizes interoperability, flexibility, and ease of adoption across diverse toolchains and environments. | |
| **A:** Unlike proprietary event formats or tool-specific integrations, CDEvents is an open, vendor-neutral specification focused solely on SDLC events. It emphasizes interoperability, flexibility, and ease of adoption across diverse toolchains and environments. | |
There was a problem hiding this comment.
By saying 'Continuous Delivery' here, it almost implies that are all the events we have. This is solving SDLC interoperability in the CI/CD space, but might not necessarily be CD or CI.
|
@xibz I have made suggested changes please go through them and let me know if anything else is required |
|
@sarthaknimbalkar I added the labels. Could you fix the DCO check please? |
Signed-off-by: sarthaknimbalkar <[email protected]>
Signed-off-by: sarthaknimbalkar <[email protected]>
Signed-off-by: sarthaknimbalkar <[email protected]>
sarthaknimbalkar
force-pushed
the
main
branch
from
914a496
to
2987af1
Compare
|
@afrittoli Done |
|
@sarthaknimbalkar I think there's some inconsistencies with the fixes, e.g. SDLC versus it spelled out software development cycle, but I dont think that's a blocker. @afrittoli I am okay merging this in, but we may want address the inconsistencies at a later point |
This pull request introduces a new FAQ.md file aimed at providing clear and concise answers to frequently asked questions regarding CDEvents. The goal of this document is to enhance user experience by offering quick access to essential information about CDEvents, its features, implementation, and community engagement.
Key Sections Added: