Repository: freedomofpress/securedrop

Issue:
update_version.sh should update new documentation
Currently the "set_up_admin_tails" documentation looks like this, I suspect that between every release FPF just increments the number (from .3.6 to .3.7). Luckily we have computers to automate small tasks for us :-)  Is there a programmatic way to do this? 

```
cd securedrop/
git checkout 0.3.6
git tag -v 0.3.6
```



Discussion:
Also I can't seem to tag the latest release, or at least I am getting thrown an error verifying @garrettr's key 

```
user@hostname: git checkout 0.3.7
HEAD is now at 3a7e1dd... SecureDrop 0.3.7
user@hostname: git tag -v 0.3.7
object 3a7e1ddc63e56282ad28982f8a4552ad689d0e63
type commit
tag 0.3.7
tagger Garrett Robinson <garrett@freedom.press> 1464915950 -0700
SecureDrop 0.3.7
gpg: Signature made Thu 02 Jun 2016 08:22:48 PM CDT using RSA key ID 4833B9A3
gpg: Can't check signature: public key not found
error: could not verify the tag '0.3.7'
```

my git repo is up to date from the latest release:

```
user@hostname:git log -p | head -n 6
commit 3a7e1ddc63e56282ad28982f8a4552ad689d0e63
Author: Garrett Robinson <garrett@freedom.press>
Date:   Thu Jun 2 17:52:40 2016 -0700

    SecureDrop 0.3.7
```

Hey @freddymartinez9. Per our installation documentation, you should have fetched the key to the Admin Workstation during the install process. See: https://docs.securedrop.org/en/latest/set_up_admin_tails.html under "Verify the Release Tag". If you run that `gpg --recv-key` command in that doc, then you will be able to verify the git tag.

@freddymartinez9 Also, I'm noting from your shell prompt that you don't seem to be on Tails. What is `user@hostname`?

yes it is a tails drive. the user is not amnesia because I was working
around an issue with DNS in tails (failing to resolve) so I've loaded the
Persistent volume in a dedicated qubes VM. If that's an absolute no-no from
a security perspective, let me know. I suspect that also triggered the GPG
error (no keyring to check against). I'll test again...

On Fri, Jun 10, 2016 at 10:40 Kevin M. Gallagher notifications@github.com
wrote:

> @freddymartinez9 https://github.com/freddymartinez9 Also, I'm noting
> from your shell prompt that you don't seem to be on Tails. What is
> user@hostname?
> 
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> https://github.com/freedomofpress/securedrop/issues/1325#issuecomment-225217792,
> or mute the thread
> https://github.com/notifications/unsubscribe/AC9OPK8bLuSBsdkCLu_xJR5UOLrtU9ZRks5qKYVcgaJpZM4IzD-I
> .

@freddymartinez9 If you are not working with Tails persistence, then you don't have our `tails_files` customizations, your GPG keyring in `GNUPGHOME`, additions to `torrc`, and SSH aliases. You'd have to hack a whole bunch of things to get it to work.. I can't comment on the security of your setup, but it is definitely not recommended by us to administer or upgrade SecureDrop in this unconventional manner.

You did point out a valid issue, in that the version number in that part of our docs has not been updated yet. Thanks for that.

@freddymartinez9 Regarding https://github.com/freedomofpress/securedrop/issues/1325#issuecomment-225217792 and https://github.com/freedomofpress/securedrop/issues/1325#issuecomment-225222667 - just so you know, there's only so much we can do to help you if you customize your SecureDrop installation. We have too many installations to support and too few staff to deal with issues that are caused by custom configuration - you are solely responsible for debugging and maintaining any customizations you make to the official SecureDrop code.

> Luckily we have computers to automate small tasks for us :-) Is there a programmatic way to do this?

There is, see `update_version.sh`. Unfortunately, when we transitioned our documentation from a bunch of Markdown files to ReadTheDocs, we did not update `update_version.sh` accordingly. Thanks for catching this!

There are two problems to fix here:
1. The current "stable" documentation for 0.3.7 incorrectly specifies version 0.3.6 in one or more locations. For example: https://docs.securedrop.org/en/stable/set_up_admin_tails.html#verify-the-release-tag.
2. `update_version.sh` should be fixed so it correctly bumps all references to the stable version number in the new documentation. Unfortunately, this might be a little tricky because there is an increasing number of references to specific version numbers throughout the documentation and it is important to avoid accidentally bumping those as well.
   
   I think we should:
   1. Add more `sed` calls in `update_version.sh` to search-and-replace the stable version number in the _new_ documentation.
   2. Where necessary, ensure that the `sed` calls will not have any unwanted side effects. This should be easy because we are calling `sed` on specific files, instead of recursively on the entire `docs/` directory.
   3. Add a note to the [Documentation Guidelines](https://docs.securedrop.org/en/stable/development/documentation.html) to remind people to update `update_version.sh` whenever they add a new reference to "the current stable version number" in the documentation.
      1. Alternatively, there might be a way to programmatically specify this in Sphinx, i.e. like a template variable `{{ current_securedrop_version }}`. In fact, that would be the best long term solution, if it is possible.

This issue suffers from the same difficulty as https://github.com/freedomofpress/securedrop/pull/1322#issuecomment-225064393. How do we merge fixes to the 0.3.7 docs when they are auto-generated from the 0.3.7 signed git tag, and we are not allowed to rebase/force-push signed tags?


Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -59,9 +59,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.3.5'
+version = '0.3.7'
 # The full version, including alpha/beta/rc tags.
-release = '0.3.5'
+release = '0.3.7'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.


Test patch: