add git intro to CONTRIBUTING.md
[ach-master.git] / CONTRIBUTING.md
index 1a02041..7994236 100644 (file)
@@ -1,20 +1,35 @@
 ## Contributing to BetterCrypto: Applied Crypto Hardening
 
-First off: thanks for helping out, every reviewer, committer and person
+First off: thanks for helping out! Every reviewer, committer and person
 interested in discussing our document and changes is a valuable addition
-to the project.
+to the project. Everybody is invited to work on this document and share
+their experience and expertise with us or ask questions if something
+isn't clear to them.
 
 Here's a few things we'd like you to consider when contributing to this
 project as some issues and discussions seem to creep up on us every now
 and again or have already been discussed at length in the past. This
 does not only make it easier for us to incorporate your changes,
-feedback or critique but might also save you some valuable time.
+feedback or critique but might also save you some valuable time.
 
-### Before you open a Pull Request (PR) on GitHub:
+### General Information
 
-1. Search open and closed issues for duplicates or previous discussions
+* GitHub is used for Pull Requests, Code Review and PR related
+  discussion.
+* The main (publicly read-only) repository is hosted at
+https://git.bettercrypto.org/ach-master.git
+* The [Applied Crypto Hardening mailing-list](https://lists.cert.at/cgi-bin/mailman/listinfo/ach) is the appropriate place for discussion
+  and source of information regarding larger changes throughout the document,
+  it's style, policy & in-depth discourse on minor and major details of the
+  guide we're working on. It's also a good place for general
+cryptography-, software-, appliance- or administrative related questions that may arise when reading or reviewing this document.
+
+### Before you open a Pull Request (PR) on GitHub
+
+1. [Search open and closed
+   issues](https://github.com/BetterCrypto/Applied-Crypto-hardening/pulls?utf8=%E2%9C%93&q=) for duplicates or previous discussions
    related to the changes you propose.
-2. Please take some time to read up on the mailing list - over the years
+2. Please take some time to read up on the [mailing list archives](https://lists.cert.at/pipermail/ach/) - over the years
    we've discussed quite a few topics in depth and you might just find
     the answer you were looking for or the reason we chose a certain
    configuration setting.
@@ -22,17 +37,18 @@ feedback or critique but might also save you some valuable time.
    requests, refactor sections of the document or change security
    critical settings in recommended service configuration files.
 
+*If you're not yet familiar with working with git we recommend giving
+https://try.github.io a shot. You'll know enough about git to work on
+this document in 15 minutes or less.*
+
 ### Attribution
 
 Feel free to add your name/handle to `src/acknowledgements.tex` (alphabetical
 order).
 
-### Resources
-
-* [Searching GitHub Pull Requests](https://github.com/BetterCrypto/Applied-Crypto-hardening/pulls?utf8=%E2%9C%93&q=)
-* [Mailing-list Archive](https://lists.cert.at/pipermail/ach/)
-
+### Get started
 
+Clone, branch and commit or start a discussion on our mailing-list!
 
 
 Thank you kindly! We hope you'll enjoy working with us on this document.