RELEASE_ENGINEERING.txt

# Branches and Tags:

There are 3 branches/tags:

* **HEAD:** The cutting edge of development.
* **tag stable:** Stable enough for use by most people.
* **tag production:** Burned in long enough that we are confident it can be widely adopted.

If you are packaging Blackbox for distribution, you should track the *tag production*.  You might also want to provide a separate package that tracks *tag stable:* for early adopters.

# Build Tasks

# Stable Releases

Marking the software to be "stable":

Step 1. Tag it.

```
git pull
git tag -d stable
git push origin :stable
git tag stable
git push origin tag stable
```

Step 2. Mark your calendar 1 week from today to check
to see if this should be promoted to production.


# Production Releases

If no bugs have been reported a full week after a stable tag has been pushed, mark the release to be "production".

```
git fetch
git checkout stable
git tag -d production
git push origin :production
git tag production
git push origin tag production
R="v1.$(date +%Y%m%d)"
git tag "$R"
git push origin tag "$R"
```

# Updating MacPorts (automatic)

Step 1: Generate the Portfile

```
tools/macports_report_upgrade.sh  1.20150222
```

This script will generate a file called `Portfile-vcs_blackbox.diff` and instructions on how to submit it as a update request.

Step 2: Submit the update request.

Submit the diff file as a bug as instructed. The instructions should look like this:

* PLEASE OPEN A TICKET WITH THIS INFORMATION:
    https://trac.macports.org/newticket
* Summary: `vcs_blackbox @1.20150222 Update to latest upstream`
* Description: ```New upstream of vcs_blackbox.
github.setup and checksums updated.```
* Type: `update`
* Component: `ports`
* Port: `vcs_blackbox`
* Keywords: `maintainer`
* Attach this file: `Portfile-vcs_blackbox.diff`

Step 3: Watch for the update to happen.

# Updating MacPorts (manual)

This is the old, manual, procedure.  If the automated procedure work, these notes may or may not be helpful.

The ultimate result of the script should be a `diff -u Portfile.orig Portfile`.  The new `Portfile` should have these changes:

1. The `github.setup` line should have a new version number.
2. The `checksums` line(s) should have updated checksums.

How to generate the checksums?

The easiest way is to to make a Portfile with incorrect checksums, then run `sudo port -v checksum vcs_blackbox` to see what they should have been.  Fix the file, and try again.

When the the checksum command works, run `port lint vcs_blackbox` and make sure it has no errors.

Some useful commands:

Change repos in sources.conf:
```
sudo vi /opt/local/etc/macports/sources.conf
  Add this line early in the file:
  file:///var/tmp/ports
```

Add a local repo in an automated manner:
```
fgrep >/dev/null -x 'file:///var/tmp/ports' /opt/local/etc/macports/sources.conf || sudo sed -i -e '1s@^@file:///var/tmp/ports\'$'\n@' /opt/local/etc/macports/sources.conf
```

Remove the local repo in an automated manner:
```
sudo sed -i -e '\@^file:///var/tmp/ports@d' /opt/local/etc/macports/sources.conf
```

Test a Portfile:
``` 
sudo port uninstall vcs_blackbox
sudo port clean --all vcs_blackbox
rm -rf ~/.macports/opt/local/var/macports/sources/rsync.macports.org/release/tarballs/ports/security/vcs_blackbox/
rm -rf /var/tmp/ports
mkdir -p /var/tmp/ports/security/vcs_blackbox
cp Portfile /var/tmp/ports/security/vcs_blackbox
cd /var/tmp/ports && portindex
sudo port -v checksum vcs_blackbox
sudo port install vcs_blackbox
```