libk  Changes To rules

Initial version of "rules"

            1  +# rules
            2  +this page is an evolving list of the libk project's official rules.
            3  +
            4  +## coding rules
            5  +1. when in doubt, ask yourself, "is this better than glibc?"
            6  +2. always include a block comment at the top source files you contribute that includes the file name, the name of the function it defnes (if any), your name/handle, and a brief outline of the file's purpose. try to follow the pattern of existing files.
            7  +3. create one file per function. if you add extra supporting functions to a file, they must not be included in the header, and must be marked `static` to prevent them from being exported. helper functions do not need to follow any namespacing convention, as they are not exported.
            8  +4. in your C, do not rely on any headers that are not defined within libk itself.
            9  +5. assembly code should compile under yasm and nasm. intel syntax is required, and inline assembly in C files is forbidden as it creates a maintenance nightmare and is non-standard.
           10  +6. write as little assembly as possible. remember that every line of assembly you write is another line . assembly should only be used for those tasks that absolutely cannot be accomplished with C.
           11  +7. comment your assembly very thoroughly. nearly every line should have a paragraph explaining its purpose in context, to aid porting and make the libk source useful as a tool for understanding how systems function at a low level.
           12  +8. try to maintain clean abstractions, but keep in mind that abstraction should always serve a material purpose. never mix layers of abstractions, as this can make it hard to maintain clean separation between OS-specific code and general-purpose code.
           13  +9. do not create new modules without first consulting the rest of the libk team.
           14  +
           15  +## community rules
           16  +1. for the time being, the project maintainer is the final arbiter over both technical and social issues. however, if a solid core leadership team can be established, it may be in the project's best interest to transition from autocracy to oligarchy.
           17  +
           18  +the team is currently still small enough that no further community rulemaking has yet been necessary.