CONTRIBUTING.md

   1 ## Contributing to BetterCrypto: Applied Crypto Hardening
   2
   3 First off: thanks for helping out! Every reviewer, committer and person
   4 interested in discussing our document and changes is a valuable addition
   5 to the project. Everybody is invited to work on this document and share
   6 their experience and expertise with us or ask questions if something
   7 isn't clear to them.
   8
   9 Here's a few things we'd like you to consider when contributing to this
  10 project as some issues and discussions seem to creep up on us every now
  11 and again or have already been discussed at length in the past. This
  12 does not only make it easier for us to incorporate your changes,
  13 feedback or critique - but might also save you some valuable time.
  14
  15 ### General Information
  16
  17 * GitHub is used for Pull Requests, Code Review and PR related
  18   discussion.
  19 * The main (publicly read-only) repository is hosted at
  20 https://git.bettercrypto.org/ach-master.git
  21 * The [Applied Crypto Hardening mailing-list](https://lists.cert.at/cgi-bin/mailman/listinfo/ach) is the appropriate place for discussion
  22   and source of information regarding larger changes throughout the document,
  23   it's style, policy & in-depth discourse on minor and major details of the
  24   guide we're working on. It's also a good place for general
  25 cryptography-, software-, appliance- or administrative related questions that may arise when reading or reviewing this document.
  26
  27
  28 ### Before you open a Pull Request (PR) on GitHub
  29
  30 1. [Search open and closed
  31    pull requests](https://github.com/BetterCrypto/Applied-Crypto-hardening/pulls?utf8=%E2%9C%93&q=) for duplicates or previous discussions
  32    related to the changes you propose.
  33 2. Please take some time to read up on the [mailing list archives](https://lists.cert.at/pipermail/ach/) - over the years
  34    we've discussed quite a few topics in depth and you might just find
  35     the answer you were looking for or the reason we chose a certain
  36    configuration setting.
  37 3. Please  write a meaningful PR title and describe
  38    your proposed changes in the text-field. This can be done quickly
  39    in a few sentences or bullet points. *Remember: other people need
  40    to review your changes and it'll make it easier for them if you make
  41    clear what you're trying to achieve.* Lastly,..
  42 4. If in doubt, just ask on the mailing list. For example, also; when opening large
  43    pull requests, refactoring whole sections of the document or if you're changing
  44    security critical settings in configuration files we recommend.
  45
  46
  47 ### Attribution
  48
  49 Feel free to add your name or handle to `src/acknowledgements.tex` (alphabetical
  50 order).
  51
  52 ### Get started
  53
  54 **Fork/clone, branch and commit or start a discussion on our mailing-list!**
  55
  56 * If you're not yet familiar with using `git` we recommend giving
  57 https://try.github.io a shot. You'll know enough about `git` to work on
  58 this document in 15 minutes or less.
  59 * Although our `LaTeX` source is mostly self-explanatory, if you're
  60 uncertain how to edit our guide correctly you might want to take a look at:
  61    * [Introduction to using TeX](http://www.math.harvard.edu/texman/)
  62    * [The Not So Short Introduction to LaTeX](https://tobi.oetiker.ch/lshort/lshort.pdf)
  63    * ..or ask on our [mailing-list for help](mailto:ach@lists.cert.at).
  64
  65 Thank you kindly! We hope you'll enjoy working with us on this document.
  66