From 7383e73f4b43b914b766d3d1688e1ba96b9712a0 Mon Sep 17 00:00:00 2001 From: Ian Moffett Date: Mon, 25 Dec 2023 21:17:00 -0500 Subject: docs: Add better contribution guidelines Signed-off-by: Ian Moffett --- README | 1 + share/misc/contrib | 134 ++++++++++++++++++++++++++++++++++ share/misc/style | 209 ----------------------------------------------------- 3 files changed, 135 insertions(+), 209 deletions(-) create mode 100644 share/misc/contrib delete mode 100644 share/misc/style diff --git a/README b/README index 5017442..5a9175e 100644 --- a/README +++ b/README @@ -29,6 +29,7 @@ After the cross compiler is done building you can build and run the project in a Documentation: -------------- Documentation will be in the form of comments throughout the codebase and can also be found in the share/ directory within the project root. +For information on contributing, please check: share/misc/contrib License: -------- 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 +-- + + +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 +-- + +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 - -/* - * 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 /* first, */ -#include /* next, */ -#include /* and then the rest, */ -#include /* sorted lexicographically. */ -#include -#include - - -/* - * 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; -} -- cgit v1.2.3