docs: reorganize responsibilities and capabilities sections in README.md #719

HmbleCreator · 2024-10-22T17:19:47Z

Closes #485

This PR reorganizes the documentation in README.md to better structure the responsibilities and capabilities sections. The changes:

Changes

Restructured "Responsibilities" section to clearly outline the library's core functions
Reorganized "Capabilities" section into logical subsections:
- Enums
- Data Models (Core and Vulnerability)
- Utilities
- CycloneDX Specification Support
Improved readability with consistent formatting and hierarchical organization

No Changes To

Functionality
API
Dependencies
Installation instructions
Usage examples
Other documentation sections

Testing

Verified all links remain functional
Checked Markdown formatting
Ensured all existing content is preserved

Similar to the organization in:
https://github.com/CycloneDX/cyclonedx-php-library#responsibilities

Signed-off-by: Humble Creator <[email protected]>

Reorganizes the responsibilities and capabilities sections for better clarity and organization, as requested in issue CycloneDX#485 Signed-off-by: Humble Creator <[email protected]>

README.md

Signed-off-by: Humble Creator <[email protected]>

jkowalleck

thank you for your effort,
please see my remarks below

README.md

jkowalleck · 2024-10-24T11:50:34Z

README.md

-
-## Documentation
-
-View the documentation [here](https://cyclonedx-python-library.readthedocs.io/).


please bring back the paragraph that links to the rendered documentation.

README.md

jkowalleck · 2024-10-24T11:52:25Z

README.md

+
+## Capabilities
+
+* Enums for the following use cases:


are there not much ore enums?

jkowalleck · 2024-10-24T11:52:36Z

README.md

+   * `ExternalReferenceType`
+   * `HashAlgorithm`
+   * `LicenseAcknowledgement`
+* Data models for the following use cases:


are there not much more models?

jkowalleck · 2024-10-24T11:53:29Z

README.md

+   * `1.3`
+   * `1.2`
+   * `1.1`
+* Normalizers that convert data models to JSON structures


nope, there are no normalizers in this library. this appears to be a copy-past artifact.

jkowalleck · 2024-10-24T11:54:49Z

README.md

+   * `Property`, `PropertyRepository`
+   * `Tool`, `ToolRepository`
+* Utilities for the following use cases:
+   * Generate valid random SerialNumbers for `Bom.serialNumber`


really? where?

README.md

jkowalleck · 2024-10-24T11:57:53Z

README.md

+bom.metadata.component.dependencies.add(component_a.bom_ref)
+```
+
+## Schema Support


nice to have, but not in the readme.
you may craft such a section in the docs.

jkowalleck · 2024-10-24T11:59:37Z

README.md


-See our [CHANGELOG][chaneglog_file].


please bring back the link to the changelog.

Key changes made: Added several missing enums based on the test files Removed LicenseAcknowledgement as it wasn't found in the test files Added missing models based on the model directory structure Removed the serial number generation utility as there wasn't clear evidence of its existence Organized models into logical groupings for better readability Signed-off-by: Humble Creator <[email protected]>

jkowalleck

these are great improvements.

lets discuss the reasoning behind the grouping of the models.

jkowalleck · 2024-10-25T07:38:02Z

README.md

+* 1.4
+* 1.3
+* 1.2
+* 1.1


1.0 is missing.
we do have support for it, dont we?

jkowalleck · 2024-10-25T07:39:37Z

README.md

@@ -56,30 +153,29 @@ See the [LICENSE][license_file] file for the full license.
 [jake]: https://github.com/sonatype-nexus-community/jake

 [license_file]: https://github.com/CycloneDX/cyclonedx-python-lib/blob/master/LICENSE


please order the links back like they were.
file-links were grouped, shield-links were grouped, external-links were grouped ...

jkowalleck · 2024-10-25T07:41:21Z

README.md

+* `Property` - Property handling
+* `Tool` - Tool representation
+
+#### Repository Models


the repositories are a mere collection of other tools.
please put them to their respective domain group

jkowalleck · 2024-10-25T07:43:17Z

README.md

+* `VulnerabilityScoreSource` - Vulnerability score source types
+* `VulnerabilitySeverity` - Vulnerability severity types
+
+### Data Models


could you explain the idea behind this grouping? how is this organized, how came this together?
I really love to understand your reasoning. You might have fresh ideas that are beneficial for the project :-) please share your thoughts.

I mean, all these models were based of CycloneDX spec -- they actually reflect it.
If a grouping was actually necessary, it should correlate with the CycloneDX spec groups somehow.

jkowalleck · 2024-10-25T07:47:44Z

README.md

+* `ToolRepository` - Tool management
+
+### Utilities
+* Serial number generation for BOMs


i did not know we have this. could you point me to the code that does this?

jkowalleck · 2024-10-25T07:48:05Z

README.md

+### Utilities
+* Serial number generation for BOMs
+* Hash calculation helpers
+* License expression parsing


i did not know we have this. could you point me to the code that does this?

jkowalleck · 2024-10-25T07:48:41Z

README.md

+* Serial number generation for BOMs
+* Hash calculation helpers
+* License expression parsing
+* XML/JSON serialization helpers


we do have this, but we dont want to brag about it, thse are mere internal helpers for experts. we better not tell about them here.
please remove,

jkowalleck · 2024-10-25T07:49:27Z

README.md

+
+### Utilities
+* Serial number generation for BOMs
+* Hash calculation helpers


we do have this, but we dont want to brag about it, these are mere helpers for experts. we better not tell about them here.
please remove

jkowalleck · 2024-10-25T07:51:18Z

README.md

+* License expression parsing
+* XML/JSON serialization helpers
+
+### Specification Support


please make each version a code-block by surrounding it with `

jkowalleck · 2024-10-25T07:53:01Z

README.md

+
+## Capabilities
+
+### Enums


the description next to the enum types do not add much value, as they duplicate the enums name and add the word type.
i'd rather remove the additional descriptions.

jkowalleck · 2024-10-26T15:02:39Z

we just got a new set of models that needs to be added - see #701

jkowalleck · 2024-10-28T12:59:39Z

README.md


-**This package is not designed for standalone use. It is a software library.**
+> **Note**: This package is a software library not intended for standalone use. For generating Software Bill of Materials (SBOM), check out [CycloneDX Python][cyclonedx-python] or [Jake][jake].


use one of the flavors here:
https://github.com/orgs/community/discussions/16925

> [!NOTE] > Highlights information that users should take into account, even when skimming. > [!TIP] > Optional information to help a user be more successful. > [!IMPORTANT] > Crucial information necessary for users to succeed. > [!WARNING] > Critical content demanding immediate user attention due to potential risks. > [!CAUTION] > Negative potential consequences of an action.

Note
Highlights information that users should take into account, even when skimming.

Tip
Optional information to help a user be more successful.

Important
Crucial information necessary for users to succeed.

Warning
Critical content demanding immediate user attention due to potential risks.

Caution
Negative potential consequences of an action.

jkowalleck · 2024-11-04T14:16:21Z

The efforts are appreciated very much. 💟
They just need an updated in accordance with the latest development. I am sorry for the inconvenience.

I've just put this very PR in "draft" mode.
Feel free to change it to "ready for review" anytime it was updated, @HmbleCreator

HmbleCreator · 2024-11-04T14:26:09Z

The efforts are appreciated very much. 💟 They just need an updated in accordance with the latest development. I am sorry for the inconvenience.

I've just put this very PR in "draft" mode. Feel free to change it to "ready for review" anytime it was updated, @HmbleCreator

Thankyou for your concern but I won't be able to work on it for a while, my end sem exams are ahead. As soon as I'll be free I'll work on it right away.

HmbleCreator added 3 commits October 22, 2024 22:24

Update README.md

e5ab2e1

Signed-off-by: Humble Creator <[email protected]>

Update README.md

75aff7d

Signed-off-by: Humble Creator <[email protected]>

docs: reorganize responsibilities and capabilities sections

87cefee

Reorganizes the responsibilities and capabilities sections for better clarity and organization, as requested in issue CycloneDX#485 Signed-off-by: Humble Creator <[email protected]>

HmbleCreator marked this pull request as ready for review October 22, 2024 17:20

HmbleCreator requested a review from a team as a code owner October 22, 2024 17:20

HmbleCreator marked this pull request as draft October 22, 2024 17:20

jkowalleck mentioned this pull request Oct 22, 2024

[DOCS] list responsibilities and capabilities #485

Open

jkowalleck added the documentation Improvements or additions to documentation label Oct 22, 2024

jkowalleck changed the title ~~docs: reorganize responsibilities and capabilities sections in README.md~~ [WIP] docs: reorganize responsibilities and capabilities sections in README.md Oct 22, 2024

jkowalleck requested changes Oct 22, 2024

View reviewed changes

README.md Show resolved Hide resolved

HmbleCreator added 12 commits October 24, 2024 11:26

Update README.md

3cef6e2

Signed-off-by: Humble Creator <[email protected]>

Update README.md

9eb0920

Signed-off-by: Humble Creator <[email protected]>

Update README.md

4c44e9e

Signed-off-by: Humble Creator <[email protected]>

Update README.md

bc44433

Signed-off-by: Humble Creator <[email protected]>

Update README.md

69e3c0b

Signed-off-by: Humble Creator <[email protected]>

Update README.md

b075177

Signed-off-by: Humble Creator <[email protected]>

Update README.md

35b4b66

Signed-off-by: Humble Creator <[email protected]>

Update README.md

b63581f

Signed-off-by: Humble Creator <[email protected]>

Update README.md

60acdd1

Signed-off-by: Humble Creator <[email protected]>

Update README.md

cfbda92

Signed-off-by: Humble Creator <[email protected]>

Update README.md

e9149fe

Signed-off-by: Humble Creator <[email protected]>

Merge branch 'CycloneDX:main' into main

89da056

HmbleCreator marked this pull request as ready for review October 24, 2024 07:09

HmbleCreator requested a review from jkowalleck October 24, 2024 07:12

jkowalleck changed the title ~~[WIP] docs: reorganize responsibilities and capabilities sections in README.md~~ docs: reorganize responsibilities and capabilities sections in README.md Oct 24, 2024

jkowalleck requested changes Oct 24, 2024

View reviewed changes

HmbleCreator added 2 commits October 24, 2024 19:19

Merge branch 'main' into main

da87ed0

jkowalleck requested changes Oct 25, 2024

View reviewed changes

jkowalleck reviewed Oct 28, 2024

View reviewed changes

jkowalleck marked this pull request as draft November 4, 2024 14:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: reorganize responsibilities and capabilities sections in README.md #719

docs: reorganize responsibilities and capabilities sections in README.md #719

HmbleCreator commented Oct 22, 2024

jkowalleck left a comment

jkowalleck Oct 24, 2024

jkowalleck Oct 24, 2024

jkowalleck Oct 24, 2024 •

edited

Loading

jkowalleck Oct 24, 2024

jkowalleck Oct 24, 2024

jkowalleck Oct 24, 2024

jkowalleck Oct 24, 2024

jkowalleck left a comment

jkowalleck Oct 25, 2024

jkowalleck Oct 25, 2024

jkowalleck Oct 25, 2024

jkowalleck Oct 25, 2024

jkowalleck Oct 25, 2024

jkowalleck Oct 25, 2024

jkowalleck Oct 25, 2024

jkowalleck Oct 25, 2024

jkowalleck Oct 25, 2024

jkowalleck Oct 25, 2024

jkowalleck commented Oct 26, 2024

jkowalleck Oct 28, 2024 •

edited

Loading

jkowalleck commented Nov 4, 2024

HmbleCreator commented Nov 4, 2024 •

edited

Loading


		## Documentation

		View the documentation [here](https://cyclonedx-python-library.readthedocs.io/).

		@@ -56,30 +153,29 @@ See the [LICENSE][license_file] file for the full license.
		[jake]: https://github.com/sonatype-nexus-community/jake

		[license_file]: https://github.com/CycloneDX/cyclonedx-python-lib/blob/master/LICENSE


		This package is not designed for standalone use. It is a software library.
		> Note: This package is a software library not intended for standalone use. For generating Software Bill of Materials (SBOM), check out [CycloneDX Python][cyclonedx-python] or [Jake][jake].

docs: reorganize responsibilities and capabilities sections in README.md #719

Are you sure you want to change the base?

docs: reorganize responsibilities and capabilities sections in README.md #719

Conversation

HmbleCreator commented Oct 22, 2024

Changes

No Changes To

Testing

jkowalleck left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jkowalleck Oct 24, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jkowalleck left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jkowalleck commented Oct 26, 2024

jkowalleck Oct 28, 2024 • edited Loading

Choose a reason for hiding this comment

jkowalleck commented Nov 4, 2024

HmbleCreator commented Nov 4, 2024 • edited Loading

jkowalleck Oct 24, 2024 •

edited

Loading

jkowalleck Oct 28, 2024 •

edited

Loading

HmbleCreator commented Nov 4, 2024 •

edited

Loading