Add contributing guidelines, and a page explaining the repo's file and folder structure.

diff --git a/codebase_structure.md b/codebase_structure.md
new file mode 100644 (file)
index 0000000..98cd6ae
--- /dev/null
+++ b/codebase_structure.md
@@ -0,0 +1,41 @@
+# Codebase Structure
+
+These are the folders and some key files used to generate and store various unified hosts files.
+
+## Data folders
+
+There are two facets of the hosts files generated by
+[/updateHostsFile.py](https://github.com/StevenBlack/hosts/blob/master/updateHostsFile.py):
+
+### Basic hosts
+Basic hosts are domains that purvey advertising, malware, tracking, coin
+mining and other abominable behavior. These hosts are included in all our products.
+
+The [/data](https://github.com/StevenBlack/hosts/tree/master/data) folder holds the
+metadata and latest hosts for all our basic hosts sources. The hosts are updated
+automatically by`/updateHostsFile.py` which iterates all the subfolders within `./data`.
+
+### Optional hosts extensions
+Hosts extensions include domains that push potentially addictive content like `porn`, `fake news`,
+`gambling`, and `social` media.
+
+The [/extensions](https://github.com/StevenBlack/hosts/tree/master/extensions) folder holds
+metadata and latest hosts for all our basic hosts sources. The hosts are updated
+automatically by`/updateHostsFile.py` which iterates all the subfolders within `./extensions`.
+
+## Product folders
+
+### Basic hosts
+The [basic hosts file](https://github.com/StevenBlack/hosts/blob/master/hosts), containing
+just adware, malware, etc, is store in the root folder of this repository.
+
+The [/hosts/alternates](https://github.com/StevenBlack/hosts/tree/master/alternates) this folder
+contains the products of `updateHostsFile.py`, one subfolder for each permutation of
+fakenews, gambling, porn, and social media hosts, all of which include the base extensions
+containing hosts that block adware, malware, tracking, etc.
+
+## Other notable files
+
++ [./readme_template.md](https://github.com/StevenBlack/hosts/blob/master/readme_template.md):
+is used to generate the all the various readme files in this repository.  Therefore,
+if you wish to change the readme, you need to change only this file.

diff --git a/contributing.md b/contributing.md
new file mode 100644 (file)
index 0000000..4e2fedd
--- /dev/null
+++ b/contributing.md
@@ -0,0 +1,39 @@
+# Contributing Guide
+
+- Contributing to Hosts is easy. This document shows you how to get started
+
+## General
+- The [Codebase Structure](https://github.com/StevenBlack/hosts/blob/master/codebase_structure.md) has
+detailed information about how the various folders and files in this project are structured.
+
+## Submitting changes
+
+- Fork the repo
+  - <https://github.com/StevenBlack/hosts/fork>
+- Check out a new branch based and name it to what you intend to do:
+  - Example:
+    ````
+    $ git checkout -b BRANCH_NAME
+    ````
+    If you get an error, you may need to fetch first, by using
+    ````
+    $ git remote update && git fetch
+    ````
+  - Use one branch per fix / feature
+- Commit your changes
+  - Please provide a git message that explains what you've done
+  - Please make sure your commits follow the [conventions](https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53#file-commit-message-guidelines-md)
+  - Commit to the forked repository
+  - Example:
+    ````
+    $ git commit -am 'Add some fooBar'
+    ````
+- Push to the branch
+  - Example:
+    ````
+    $ git push origin BRANCH_NAME
+    ````
+- Make a pull request
+  - Make sure you send the PR to the <code>BRANCH_NAME</code> branch
+
+If you follow these instructions, your Pull Request will land safely!

diff --git a/readme_template.md b/readme_template.md
index 41069cfd8bd2dd2b1c3b6854d5b2965a89da774a..2d6af634464c1bddb4d228f74b360df4bed7ee9f 100644 (file)
--- a/readme_template.md
+++ b/readme_template.md
@@ -388,6 +388,8 @@ devices under a variety of operating systems.
 
 ## Contribute!
 
+Please read our [Contributing Guide](https://github.com/StevenBlack/hosts/blob/master/contributing.md). Among other things, this explains how we organize files and folders in this repository.
+
 We are always interested in discovering well-curated sources of hosts.  If you find one, please open an [issue](https://github.com/StevenBlack/hosts/issues) to draw our attention.
 
 Before you create or respond to any issue, please read our [code of conduct](https://github.com/StevenBlack/hosts/blob/master/code_of_conduct.md).