Skip to content

Update component best practices guide for 2.4

Sam requested to merge uc-parent/uc-private/highgate/opencpi:update-component-best-practices-guide-v2_4 into develop

What this MR does / why we need it:

This merge request updates the Component Best Practices Guide. All the modifications are listed below should they need to be carried over in another format:

  1. Add to Revision History table: "2.4", "Remove ctl_in.is_operating content and add that a protocol’s metadata can indicate dropped samples." | "2022-07-31"

  2. Typo "to have a specproperty for that sets writesync" -> "to have a specproperty that sets writesync"

  3. Typo (extra space after "the"!) "component specification indicates the writable attribute" -> "component specification indicates the writable attribute"

  4. Modify "A component specification and documentation may specify behavior that involves dropping data in the face of back-pressure, but this should rare and explicit and a volatile property should indicate that it happened." -> "A component specification and documentation may specify behavior that involves dropping data in the face of back-pressure, but this should be rare and explicit. A volatile property and/or a protocol metadata message should indicate that it happened."

  5. Typo "It is worker's responsibility to group" -> "It is a worker's responsibility to group"

  6. Typo "Since moving primitives between libraries effects the compatibility of the library and project" -> "Since moving primitives between libraries affects the compatibility of the library and project"

  7. "num should not be used in place of number" - All instances of this now have "num" and "number" in bold text for consistency

  8. Removed paragraph "When the control input ctl_in.is_operating is false then the component should stop. No new data will be offered to the worker if ctl_in.is_operating is false, but any other processing unrelated to the availability of input data or output port readiness should cease." (My reasoning for removing this paragraph is "ready" and "valid" cannot be high without "ctl_in.is_operating" also being high in v2 protocols, so I think it goes without saying nothing is taken on the input and no data will be output. Since the ocpi.comp.sdr upgrade to v2 protocols, "ctl_in.is_operating" no longer features in the code, so I think this information can be omitted).

Steps to complete before submitting MR:

  • I have read Contribution guidelines

  • I have ensured I have a changelog written in the imperative form that is meaningful and accurately summarizes the work done

  • I have added the release notes label if applicable (more information below)

  • I have ensured the workflow labels are up to date and will continue to do so up until this work is merged into develop

  • I have added a category, type, and target release label along with all other labels as need be

  • My branch is up to date with develop. If it is not, then I have ensured my work does not conflict with other work

  • I agree my bugfix MR does not include new features/enhancements

  • I represent that bugfixes have been locally tested against the most recent major.minor release in which the bug exists

  • (REVIEWER ONLY) I have thoroughly gone through the above steps to ensure that they have been followed

Release Notes

N/A

Changelog

enh(documentation): Update Component Best Practices Guide

Which issue(s) this MR closes

N/A

Edited by Connor Lathrop

Merge request reports