[openssl/openssl] d8e49b: Add a STYLE.md file and link it from CONTRIBUTING.md

  Branch: refs/heads/master
  Home:   https://github.com/openssl/openssl
  Commit: d8e49b85d003d4f3c4636b702f5a088bc530eaa8
      https://github.com/openssl/openssl/commit/d8e49b85d003d4f3c4636b702f5a088bc530eaa8
  Author: Bob Beck <[email protected]>
  Date:   2026-07-10 (Fri, 10 Jul 2026)

  Changed paths:
    M CONTRIBUTING.md
    A STYLE.md

  Log Message:
  -----------
  Add a STYLE.md file and link it from CONTRIBUTING.md

This is effectively, the current coding style policy web page
changed to accomodate clang-format.  This is more or less the
same file I have had in the various clang-format sample PR's since
September.

It does include an additional sections on Integers and on
Return Values that are not in the original coding style
policy

It is changed from the September version in that it does not
have mention of keeping include files self contained. I believe
that is achievable and desirable, but I think should be done
as a separate change from this.

There were a number of issues brought up in discussion of this
file in the clang-format PR's. I recorded those in 818, 819,
820, 821, 822, 823, 824, 825, and 826, which we can
link in there to the appropriate section of the document.

Reviewed-by: Neil Horman <[email protected]>
Reviewed-by: Milan Broz <[email protected]>
MergeDate: Fri Jul 10 15:37:13 2026
(Merged from https://github.com/openssl/openssl/pull/29295)


  Commit: b3020646af3c8c0c01a7ba8b64f1c63931b17c3f
      https://github.com/openssl/openssl/commit/b3020646af3c8c0c01a7ba8b64f1c63931b17c3f
  Author: Bob Beck <[email protected]>
  Date:   2026-07-10 (Fri, 10 Jul 2026)

  Changed paths:
    M CONTRIBUTING.md
    A DOCUMENTATION.md
    M STYLE.md

  Log Message:
  -----------
  Modernize and update STYLE.MD, add DOCUMENTATION.MD

So this repatriates DOCUMENTATION.MD from the web page to the
code base, and links both STYLE.MD and DOCUMENTATION.MD from
CONTRIBUTING.MD

It does a large rototilling of STYLE.MD to address many of the
outstanding concerns noted when I started this before clang-format
last year, and brings us roughly in line with the things that are
addressed in similar style guides for other projects.

Most of the changed or updated reccomendations reflect what we
currently have been doing, or have expressed as a desire to
move to in the future.

Most larger "OpenSSL-isms" I've tried to explicitly call out
to make this a more cohesive and useful guide for a new contributor

Reviewed-by: Neil Horman <[email protected]>
Reviewed-by: Milan Broz <[email protected]>
MergeDate: Fri Jul 10 15:37:16 2026
(Merged from https://github.com/openssl/openssl/pull/29295)


  Commit: c17828595f60ab0a91c54a8da7c3461387ea77a7
      https://github.com/openssl/openssl/commit/c17828595f60ab0a91c54a8da7c3461387ea77a7
  Author: Bob Beck <[email protected]>
  Date:   2026-07-10 (Fri, 10 Jul 2026)

  Changed paths:
    M DOCUMENTATION.md
    M STYLE.md

  Log Message:
  -----------
  Change the Doxygen doc requirement for non public functions

To be at the prototype site in the internal header file.

The major reason *Why* we would like to have Doxygen style comments
describing what internals do is so that they work with modern IDE's
since most common ones support them.

It's wonderful to be looking at an internal function, thinking "wtf is this",
and be able to hover over it and - boink - up comes the docs. This
typically only works (or works better) when the Doxygen comment is
at the prototype site, not if it is at the implementation site.

This also reinforces the requirement that "yes you do this for shared
functions but you don't need to for statics".

Reviewed-by: Neil Horman <[email protected]>
Reviewed-by: Milan Broz <[email protected]>
MergeDate: Fri Jul 10 15:37:18 2026
(Merged from https://github.com/openssl/openssl/pull/29295)


  Commit: a40f6f8bd67d209bb2d90baa6fad8b06a7f18a16
      https://github.com/openssl/openssl/commit/a40f6f8bd67d209bb2d90baa6fad8b06a7f18a16
  Author: Bob Beck <[email protected]>
  Date:   2026-07-10 (Fri, 10 Jul 2026)

  Changed paths:
    M STYLE.md

  Log Message:
  -----------
  Make the examples in SYTLE and DOCUMENTATON compliant.

Specifically bring them closer to the suggested naming conventions
and make them clang-format compliant.

Reviewed-by: Neil Horman <[email protected]>
Reviewed-by: Milan Broz <[email protected]>
MergeDate: Fri Jul 10 15:37:20 2026
(Merged from https://github.com/openssl/openssl/pull/29295)


Compare: https://github.com/openssl/openssl/compare/9b182491fc47...a40f6f8bd67d

To unsubscribe from these emails, change your notification settings at https://github.com/openssl/openssl/settings/notifications

-- 
You received this message because you are subscribed to the Google Groups "openssl-commits" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
To view this discussion visit https://groups.google.com/a/openssl.org/d/msgid/openssl-commits/openssl/openssl/push/refs/heads/master/9b1824-a40f6f%40github.com.