docs: Add better contribution guidelines

Signed-off-by: Ian Moffett <ian@osmora.org>

2 files changed, 134 insertions, 209 deletions

diff --git a/share/misc/contrib b/share/misc/contrib
new file mode 100644
index 0000000..625a83d
--- /dev/null
+++ b/share/misc/contrib
@@ -0,0 +1,134 @@
+==============================
+Hyra Contribution Guidelines
+==============================
+
+!! C PROGRAMMING STYLE !!
+
+The .vimrc file that follows this style can be found in
+share/misc/vimrc
+
+Indent width is 4-spaces (NO TABS)
+
+The typename must go above the function name like so:
+
+static inline bool
+is_power_of_two(uint8_t n)
+{
+    if (g_foo) {
+        ...
+    }
+
+    return ((n & 0x01) == 0);
+}
+
+When checking if an integer is 0 or not, *be explicit* unless it is a bool!
+Do not do this:
+
+#define BLAH 1
+
+if (!BLAH) {
+    ...
+}
+
+Do this instead:
+
+if (BLAH == 0) {
+    ...
+}
+
+-- or if it is a bool:
+
+#define BLAH true
+
+if (!blah) {
+    ...
+}
+
+--
+
+Now, only use predefined integer types in sys/cdefs.h like so:
+
+uint8_t a;
+uint16_t b;
+uint32_t c;
+--
+
+All includes must be done with '< >':
+
+#include <sys/cdefs.h>
+--
+
+
+When including architecture specific things, it would be stupid
+to include for another architecture. Only include from machine/ which
+points to the architecture specific files for the current architecture.
+For example:
+
+/* AMD64-specific, in sys/include/arch/amd64/lapic.h */
+#include <machine/lapic.h>
+--
+
+Avoid initializing variables to e.g. 0 unless it seems wise to do so.
+Try to avoid this:
+
+uint8_t foo = 0;
+...
+
+It is best to do this instead:
+
+uint8_t foo;
+...
+
+foo = some_calculation();
+--
+
+One of the only times it is best to do that is when you have
+a pointer, like, for example:
+
+uint8_t *ptr = NULL;
+...
+
+-- or if you have for example, some sort of counter value
+   that must have a start:
+
+uint8_t countdown = COUNTDOWN_START;
+--
+
+!! COMMIT STYLE !!
+
+Keep commits small if possible. Follow commit good practices.
+
+- Commit examples -
+1) Some manpage update:
+    docs: man: Describe foo in foobar(9)
+
+2) Adding a tool in tools/
+   build: tools: Create foo
+
+   This commit adds a new script in tools/
+   that does x and y  ...
+
+- Kernel commits -
+An example of a commit title for a non architecture-specific commit:
+  kernel: foo: Fix bar in foobar
+
+An example of an architecture specific commit e.g. for AMD64:
+kernel/amd64: foo: Add foo in bar
+
+- Ready to commit -
+
+(BE SURE TO TEST IT!! IDEALLY ON REAL HW TOO IF POSSIBLE!)
+
+* Commit with `git commit -sv`
+* Create patch with `git format-patch -1 HEAD`
+* Email patch to ian@osmora.org and for better response times,
+  optionally CC to blazt@osmora.org and bion@osmora.org
+
+Done!
+
+------------------------------------------------
+NOTE TO MAINTAINERS
+
+For those who maintain the Hyra repo, when testing a patch, apply it like so:
+`git am -s patchfile.patch`. If all good, create a new patch and email it to
+ian@osmora.org
diff --git a/share/misc/style b/share/misc/style
deleted file mode 100644
index 0a994e8..0000000
--- a/share/misc/style
+++ /dev/null
@@ -1,209 +0,0 @@
-/*
- * Copyright (c) 2023 Ian Marco Moffett and the Osmora Team.
- * All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions are met:
- *
- * 1. Redistributions of source code must retain the above copyright notice,
- *    this list of conditions and the following disclaimer.
- * 2. Redistributions in binary form must reproduce the above copyright
- *    notice, this list of conditions and the following disclaimer in the
- *    documentation and/or other materials provided with the distribution.
- * 3. Neither the name of Hyra nor the names of its
- *    contributors may be used to endorse or promote products derived from
- *    this software without specific prior written permission.
- *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
- * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
- * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
- * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
- * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
- * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
- * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
- * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
- * POSSIBILITY OF SUCH DAMAGE.
- */
-
-#include <sys/cdefs.h>
-
-/*
- * Vim config in share/misc/vimrc
- */
-
-/*
- * Metadata goes in *.c files
- */
-__KERNEL_META("$Hyra$: style.c, Ian Marco Moffett, "
-              "Hyra style guide");
-/*
- * VERY important single-line comments look like this.
- */
-
-/* Most single-line comments look like this. */
-
-/*
- * Multi-line comments look like this.  Make them real sentences.  Fill
- * them so they look like real paragraphs.
- */
-
-/*
- * Attempt to wrap lines longer than 80 characters appropriately.
- * Refer to the examples below for more information.
- */
-
-/*
- * EXAMPLE HEADER FILE.
- * A header file should protect itself against
- * multiple inclusion.
- */
-
-/*
- * If your header as a manpage tied to it use
- * write a comment similar to the below comment
- */
-
-/*
- * For documentation: See foo(9)
- */
-
- #ifndef _SYS_FOO_H_
- #define _SYS_FOO_H_
-
-
-/*
- * extern declarations must only appear in header files, not in .c
- * files, so the same declaration is used by the .c file defining it
- * and the .c file using it, giving the compiler the opportunity to
- * detect type errors.
- *
- * extern function declarations should not use the extern keyword,
- * which is unnecessary.
- *
- * Exception: A subroutine written in assembly in an adjacent .S file,
- * which is used only in one .c file, may be declared in the .c file.
- */
-extern int g_foo;
-
-int funnify(const char *s);
-
-#endif     /* !_SYS_FOO_H_ */
-
-/*
- * END OF EXAMPLE HEADER FILE
- */
-
-/*
- * If a header file requires structures, defines, typedefs, etc. from
- * another header file it should include that header file and not depend
- * on the including file for that header including both.  If there are
- * exceptions to this for specific headers it should be clearly documented
- * in the headers and, if appropriate, the documentation.  Nothing in this
- * rule should suggest relaxation of the multiple inclusion rule and the
- * application programmer should be free to include both regardless.
- */
-
-/*
- * Kernel include files come first.
- */
-#include <sys/param.h>      /* <sys/param.h> first, */
-#include <sys/types.h>      /*   <sys/types.h> next, */
-#include <sys/ioctl.h>      /*   and then the rest, */
-#include <sys/socket.h>     /*   sorted lexicographically.  */
-#include <sys/stat.h>
-#include <sys/wait.h>
-
-
-/*
- * Macros are capitalized, parenthesized, and should avoid side-effects.
- * If they are an inline expansion of a function, the function is defined
- * all in lowercase, the macro has the same name all in uppercase.
- * If the macro is an expression, wrap the expression in parentheses.
- * If the macro is more than a single statement, use ``do { ... } while (0)''
- * or ``do { ... } while (false)'', so that a trailing semicolon works.
- * Right-justify the backslashes; it makes it easier to read.
- */
-#define MACRO(v, w, x, y)               \
-    do {                                \
-        v = (x) + (y);                  \
-        w = (y) + 2;                    \
-    } while (0)
-
-};
-
-/*
- * Sometimes we want a macro to be conditionally defined for debugging
- * and expand to nothing (but still as statement) when we are not debugging:
- */
-#if defined(FOO_DEBUG)
-#define DPRINTF(...) KDEBUG(__VA_ARGS__)
-#else
-#define DPRINTF(...) __nothing
-#endif  /* defined(FOO_DEBUG) */
-
-/*
- * The function type must be declared on a line by itself
- * preceding the function.
- */
-static char *
-function(int fooy)
-{
-	/*
-	 * When declaring variables in functions, multiple variables per line
-	 * are okay. If a line overflows reuse the type keyword.
-	 *
-	 * Function prototypes and external data declarations should go in a
-	 * suitable include file.
-	 *
-	 * Avoid initializing variables in the declarations; move
-	 * declarations next to their first use, and initialize
-	 * opportunistically. This avoids over-initialization and
-	 * accidental bugs caused by declaration reordering.
-	 */
-     int foo, bar;
-
-     foo = 0;
-     bar = 0;
-	/*
-	 * Casts and sizeof's are not followed by a space.
-	 *
-	 * We parenthesize sizeof expressions to clarify their precedence:
-	 *
-	 * 	sizeof(e) + 4
-	 * not:
-	 *	sizeof e + 4
-	 *
-	 * We don't put a space before the parenthesis so that it looks like
-	 * a function call. We always parenthesize the sizeof expression for
-	 * consistency.
-	 *
-	 * On the other hand, we don't parenthesize the return statement
-	 * because there is never a precedence ambiguity situation (it is
-	 * a single statement).
-	 *
-	 * NULL is any pointer type, and doesn't need to be cast, so use
-	 * NULL instead of (struct foo *)0 or (struct foo *)NULL.  Also,
-	 * test pointers against NULL because it indicates the type of the
-	 * expression to the user. I.e. use:
-	 *
-	 *	(p = f()) == NULL
-	 * not:
-	 *	!(p = f())
-	 *
-	 * Don't use `!' for tests unless it's a boolean.
-	 * E.g. use "if (*p == '\0')", not "if (!*p)".
-	 *
-	 * Routines returning ``void *'' should not have their return
-	 * values cast to more specific pointer types.
-	 *
-	 * Prefer sizeof(*var) over sizeof(type) because if type changes,
-	 * the change needs to be done in one place.
-	 *
-	 * Prefer EXIT_FAILURE instead of random error codes.
-	 */
-
-	/* No parentheses are needed around the return value. */
-	return 0;
-}