CONTRIBUTING.md

   1 # Contributing
   2
   3 ## Branches and issues
   4 - Whenever possible, one commit per feature.
   5 - If feature/pull-request branches have only one developer, please regularly
   6   rebase them onto main until they are merged in.
   7 - Don't merge branches with meaningless commit messages; always squash them
   8   instead.
   9 - Wait for discussion of big changes. Your branches will still be here
  10   tomorrow.
  11
  12 ## Coding Style
  13 - Use lowercase filenames
  14 - Do not use underscores in filenames
  15 - File extensions:
  16
  17   Type     | Extension
  18   -------- | ---------
  19   Markdown | .md
  20   HTML     | .html
  21   JPEG     | .jpg
  22
  23 Take note about the following fileextensions is preferred over their
  24 alternatives: `.md`, `.html`, `.jpg`
  25
  26 ### Editorial content
  27 - Use British English
  28 - Abbreviate with caution
  29 - Avoid contractions
  30 - Do not use hyphens as em dashes. Em dashes do not have space around them.
  31 - Avoid jargon
  32 - Content changes require approval
  33   - If you are on freenode staff, you should know where to ask
  34   - If not, any staff can relay to the right people as appropriate
  35
  36 ### CSS
  37 - Four spaces as indentation
  38 - Opening curly bracket on the same line as the selector
  39 - One selector per line, if multiple selectors are grouped then commas +
  40   newline is used
  41 - One space between selector and opening curly brackets
  42 - Closing curly bracket should be placed on its own line with one empty line
  43   after
  44 - Rules containing only one Declaration can be put on one single line, a space
  45   is required after `{` and before `}`
  46 - Comments
  47   - One line comments (`/* ... */`) should have a space after the opening `/*`
  48     and a space before the closing `*/`
  49   - Multi line comments should have the closing `*/` on an own line, text are
  50     allowed on the same row as the opening `/*`.  Note that there must be a
  51     space after the opening `/*`.  One asterix per line, aligned with the ones
  52     in the opening and closing `/*` and `*/`, with one space after the asterix
  53 - Abbrevations are allowed if they are explained in a comment just before their
  54   first appearance. Format: `/* <abbrevation> = <expanded abbrevation>
  55   [(optional comment)] */`
  56 - All variables should be declared in `:root {}`
  57 - All custom media should be declared directly after `:root {}`
  58 - Reuse variables rather than creating new ones, if possible. (this is to keep
  59   a condensed palette)
  60 - All colors must be variables, no colors are declared after `:root { }`
  61
  62 This does not apply to third party css such as open sans, font awesome and freenode.css
  63
  64 ### HTML
  65 - Templates are [Jinja2](http://jinja.pocoo.org) based
  66 - Four spaces as indentation
  67 - No direct internal links, use `{{ url_for("") }}`
  68 - External links should include protocol, https is a must if the site linked to supports it, `target="_blank"` is preferred
  69 - Comments should only be template comments, `{#- ... #}` instead of `<!-- ... -->`
  70 - If there are a newline in an element the opening and closing tags should be on it's own lines (expanded elements)
  71 - One line elements (collapsed elements) preferably shouldn't be any longer than 80 characters.
  72 - Use lowercase element names and attributes
  73 - All elements should be closed, including empty elements such as `<meta content="" />` and `<br />`
  74 - Quote attribute values with double quotes. (use single quotes if the attribute value contains a double quote)
  75 - No inline styles are allowed
  76 - No spaces around `=`
  77
  78 A *.footerchild* should contain at least 3 items, it just look silly otherwise.
  79
  80 ### JS
  81 JavaScript should be used sparsely and should not break the usability of the site for browsers without JavaScript
  82 - For style, follow [JavaScript Standard Style](https://standardjs.com/)
  83 - Document with [jsdoc](http://usejsdoc.org/) at least to describe what every function does