move contents of HACKING.md to a doc/HOWTO

reference list of files and removed -Werror from instructions on adding
functions rename HACKING.md to HOWTO.md.

Reviewed-by: Eugene Syromiatnikov <esyr@openssl.org>
Reviewed-by: Frederik Wedel-Heinen <fwh.openssl@gmail.com>
MergeDate: Mon Apr 27 06:14:57 2026
(Merged from https://github.com/openssl/openssl/pull/18003)

diff --git a/HOWTO.md b/HOWTO.md
new file mode 100644 (file)
index 0000000..8ee3be5
--- /dev/null
+++ b/HOWTO.md
@@ -0,0 +1,8 @@
+MODIFYING OPENSSL SOURCE
+========================
+
+This is a collection of pointers to parts of the documentation that will help
+people doing modifications.
+
+* [doc/HOWTO/adding-functions.md](Adding new Functions)
+* [doc/HOWTO/documenting-functions-macros.md](Documenting Functions and Macros)

diff --git a/HACKING.md b/doc/HOWTO/adding-functions.md
similarity index 80%
rename from HACKING.md
rename to doc/HOWTO/adding-functions.md
index b58f08a2dc9acf7342159ce2ac900c21c9378754..704089a2465b8a0710cda2ce9019eff81083588f 100644 (file)
--- a/HACKING.md
+++ b/doc/HOWTO/adding-functions.md
@@ -1,5 +1,5 @@
-MODIFYING OPENSSL SOURCE
-========================
+ADDING FUNCTIONS to OPENSSL
+===========================
 
 This document describes the way to add custom modifications to OpenSSL
 sources.
@@ -58,7 +58,7 @@ public function - as defined above - is added, these files must be updated.
 
 To make such an update, please do the following:
 
-    ./Configure -Werror --strict-warnings [your-options]
+    ./Configure --strict-warnings [your-options]
     make update
 
 If you plan to submit the changes you made to OpenSSL (see
@@ -67,14 +67,19 @@ If you plan to submit the changes you made to OpenSSL (see
 
     make doc-nits
 
-Do note that `make update` also generates files related to OIDs (in the
-`crypto/objects/`  folder) and errors messages.
+`make update` ensures that your functions declarations are added to
+`util/libcrypto.num` or `util/libssl.num`.
+It also generates files related to OIDs (in the `crypto/objects/`  folder)
+and error messages.
+
+More details are at
+  [doc/HOWTO/documenting-functions-macros.md](Documenting Functions and Macros)
 
 If a git merge error occurs in one of these generated files, then the
 generated files need to be removed and regenerated using `make update`.
-To aid in this process, the generated files can be committed separately
+To aid in this process, the generated files should be committed separately
 so they can be removed easily by reverting that commit.
 
-[doc/internal/man7/build.info.pod]: ./doc/internal/man7/build.info.pod
-[Configurations/unix-Makefile.tmpl]: ./Configurations/unix-Makefile.tmpl
-[CONTRIBUTING.md]: ./CONTRIBUTING.md
+[doc/internal/man7/build.info.pod]: ../doc/internal/man7/build.info.pod
+[Configurations/unix-Makefile.tmpl]: ../../Configurations/unix-Makefile.tmpl
+[CONTRIBUTING.md]: ../../CONTRIBUTING.md