Streamline & document dependency update process.

Makefile

@@ -64,7 +64,24 @@ ${VIRTUAL_ENV}/.%.txt.installed: %.txt | ${pip}
 
 # perform 'pip freeze' on first class requirements in .in files.
 requirements.txt requirements-dev.txt: %.txt: %.in | ${pip-compile}
-	${pip-compile} ${pip-compile-args} --output-file $@ $<
+	${pip-compile} --output-file $@ $<
+
+update_requirements: _mark_outdated requirements.txt requirements-dev.txt _commit_update
+
+_mark_outdated:
+	touch requirements*.in
+
+# get latest sha for gitlab.com:icf/websecmap@master and update requirements
+update_requirement_websecmap: _update_websecmap_sha requirements.txt _commit_update
+
+_update_websecmap_sha:
+	sha=$(shell git ls-remote -q git@gitlab.com:internet-cleanup-foundation/web-security-map.git master|cut -f1); \
+	if grep $$sha requirements.in >/dev/null; then echo -e "\nNo update for you, current sha for websecmap in requirements.in is the same as master on Gitlab.\n"; exit 1;fi; \
+	sed -Ei= "s/[a-zA-Z0-9]{40}/$$sha/" requirements.in
+
+_commit_update: requirements.txt
+	git add requirements*.txt requirements*.in
+	git commit -m "Updated requirements."
 
 ## QA
 test: .make.test	## run test suite

README.md

@@ -126,6 +126,20 @@ If your shell support tab completion you can get a complete list of supported co
 make <tab><tab>
 ```
 
+## 4: Common tasks
+
+### Update dependencies/requirements
+
+Python dependencies are managed using [pip-tools](https://github.com/jazzband/pip-tools). See `requirements.in` and `requirements-dev.in`.
+
+For convenience the following command can be used to update all Python dependencies (within their version boundaries):
+
+    make update_requirements
+
+The dependency on Web Security Map is version pinned by a Git SHA in the Websecmap Gitlab repo. The following command will lookup the SHA for the current master in Gitlab, update the `requirements.in` file, update the dependencies, and even commit everything to Git.
+
+    make update_requirement_websecmap
+
 ## FAQ / Troubleshooting
 
 ### Missing xcode (mac users)

requirements.in

@@ -1,3 +1,12 @@
+# Dependencies for this project are manager using pip-tools (https://github.com/jazzband/pip-tools).
+# This is a simple management tool to manage version pinnin build on top of Pip and requirements.txt.
+
+# In this file only
+# - specify requirements that are needed for Dashboard runtime (no development requirements).
+# - no requirements that are already provided by websecmap itself
+# - no version pinning, unless it is required and explained
+
+# to update websecmap run: make update_requirement_websecmap
 git+https://gitlab.com/internet-cleanup-foundation/web-security-map@acf1e12cc6d896b92fbf3b61d4e41be0a233fce5#egg=websecmap
 
 django-otp

requirements.txt

@@ -116,11 +116,11 @@ urllib3==1.25.6           # via requests
 uwsgi==2.0.18
 validators==0.14.0
 vine==1.3.0               # via amqp, celery
-git+https://gitlab.com/internet-cleanup-foundation/web-security-map@pip-tools#egg=websecmap
+git+https://gitlab.com/internet-cleanup-foundation/web-security-map@acf1e12cc6d896b92fbf3b61d4e41be0a233fce5#egg=websecmap
 wikidata==0.6.1
 xlrd==1.2.0               # via pyexcel-xls, tablib
 xlwt==1.3.0               # via pyexcel-xls, tablib
 zipp==0.6.0               # via importlib-metadata
 
 # The following packages are considered to be unsafe in a requirements file:
-# setuptools==41.4.0        # via markdown, tldextract
+# setuptools==41.6.0        # via markdown, tldextract