libk  Changes To rules

Changes to "rules" between 2019-10-31 04:18:29 and 2019-10-31 04:45:38

     1      1   # rules
     2      2   this page is an evolving list of the libk project's official rules.
     3      3   
     4      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 that has to be ported meticulously to every single architecture we support. 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.
            5  +1. <a id="code1"></a> when in doubt, ask yourself, "is this better than glibc?"
            6  +2. <a id="code2"></a> 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. <a id="code3"></a> 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. <a id="code4"></a> in your C, do not rely on any headers that are not defined within libk itself.
            9  +5. <a id="code5"></a> 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. <a id="code6"></a> write as little assembly as possible. remember that every line of assembly you write is another line that has to be ported meticulously to every single architecture we support. assembly should only be used for those tasks that absolutely cannot be accomplished with C.
           11  +7. <a id="code7"></a> 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. <a id="code8"></a> 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. <a id="code9"></a> do not create new modules without first consulting the rest of the libk team.
    14     14   
    15     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.
           16  +1. <a id="com1"></a> 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  +2. <a id="com2"></a> if you demonstrate convincingly that you cannot keep a cool head during disagreements or keep your ego out of technical discussions, you will be removed from the team. polite constructive criticism and respectful debate are important parts of software development, but starting arguments or refusing to let go of a topic once the community has made a decision is toxic behavior that will not be tolerated.
           18  +3. <a id="com3"></a> please keep any and all drama out of the development process. you may reach out to an administrator if the behavior of someone on the team is affecting your ability to contribute, but keep in mind our primary goal is getting shit done, and this is not an appropriate place to pursue personal grievances. don't expect to be taken seriously if you haven't made any meaningful contributions to the project yourself, or if you're attempting to conduct a whisper campaign behind someone's back.
           19  +4. <a id="com4"></a> judge people by their behavior and their contributions. this is not a place for affinity-group tribalism or identity politics, and we will neither tolerate discrimination against you nor give you special treatment for irrelevant factors like race, religion, sexual orientation, or gender identity.
    17     20   
    18     21   the team is currently still small enough that no further community rulemaking has yet been necessary.