Merge pull request #10730 from edx/ned/github-txt-instructions

Add instructions to github.txt

requirements/edx/github.txt

@@ -4,6 +4,43 @@
 #   * @mollydb to check licensing
 #   * One of @e0d, @feanil, @fredsmith, @maxrothman, or @jibsheet
 #     to check system requirements
+#
+# A correct GitHub reference looks like this:
+#
+#   git+https://github.com/OWNER/REPO-NAME.git@TAG-OR-SHA#egg=KIT-NAME==VERSION
+#
+# For example:
+#
+#   git+https://github.com/edx/edx-lint.git@v0.3.2#egg=edx_lint==0.3.2
+#
+# where:
+#
+#   OWNER = edx
+#   REPO-NAME = edx-lint
+#   TAG-OR-SHA = v0.3.2
+#   KIT-NAME = edx_lint
+#   VERSION = 0.3.2
+#
+#
+# Rules to follow (even though many URLs here don't follow them!):
+#
+#   * Don't leave out any of these pieces.
+#
+#   * Don't use -e
+#
+#   * TAG-OR-SHA must be a git tag, or a git SHA.  Don't use branch names here.
+#
+#   * KIT-NAME might be different than REPO-NAME.  KIT-NAME must be the same as
+#     the `name="KIT-NAME"` value in the repo's setup.py.
+#
+#   * VERSION might not be the same as TAG-OR-SHA, but if the tag names the
+#     version, please make it match the VERSION, but with a "v" prefix.
+#     VERSION must be the same as the `version="VERSION"` value in the repo's
+#     setup.py.  An alternative is to use 0.0 as VERSION: this forces pip to
+#     re-install the package each time, and can be useful when working with two
+#     repos before picking a version number. Don't use 0.0 on master, only for
+#     tight-loop work in progress.
+
 
 # Python libraries to install directly from github