# Contributing

## Forking

[Fork this repository](https://github.com/rapid7/metasploit-concern/fork)

## Branching

Branch names follow the format `TYPE/ISSUE/SUMMARY`.  You can create it with `git checkout -b TYPE/ISSUE/SUMMARY`.

### `TYPE`

`TYPE` can be `bug`, `chore`, or `feature`.

### `ISSUE`

`ISSUE` is either a [Github issue](https://github.com/rapid7/metasploit-concern/issues) or an issue from some other
issue tracking software.

### `SUMMARY`

`SUMMARY` is is short summary of the purpose of the branch composed of lower case words separated by '-' so that it is a valid `PRERELEASE` for the Gem version.

## Changes

### `PRERELEASE`

1. Update `PRERELEASE` to match the `SUMMARY` in the branch name.  If you branched from `master`, and [version.rb](lib/metasploit/concern/version.rb) does not have `PRERELEASE` defined, then adding the following lines after `PATCH`: 
```
# The prerelease version, scoped to the {PATCH} version number.
PRERELEASE = '<SUMMARY>'
```
2. `rake spec`
3.  Verify the specs pass, which indicates that `PRERELEASE` was updated correctly.
4. Commit the change `git commit -a`

### Your changes

Make your changes or however many commits you like, commiting each with `git commit`.

### Pre-Pull Request Testing

1. Run specs one last time before opening the Pull Request: `rake spec`
2. Verify there was no failures.

### Push

Push your branch to your fork on gitub: `git push push TYPE/ISSUE/SUMMARY`

### Pull Request

* [Create new Pull Request](https://github.com/rapid7/metasploit-concern/compare/)
* Add a Verification Steps comment

```
# Verification Steps

- [ ] `bundle install`

## `rake spec`
- [ ] `rake spec`
- [ ] VERIFY no failures
```
You should also include at least one scenario to manually check the changes outside of specs.

* Add a Post-merge Steps comment

The 'Post-merge Steps' are a reminder to the reviewer of the Pull Request of how to update the [`PRERELEASE`](lib/metasploit/concern/version.rb) so that [version_spec.rb](spec/lib/metasploit/concern/version_spec.rb) passes on the target branch after the merge.

DESTINATION is the name of the destination branch into which the merge is being made.  SOURCE_SUMMARY is the SUMMARY from TYPE/ISSUE/SUMMARY branch name for the SOURCE branch that is being made.

When merging to `master`:

```
# Post-merge Steps

Perform these steps prior to pushing to master or the build will be broke on master.

## Version
- [ ] Edit `lib/metasploit/concern/version.rb`
- [ ] Remove `PRERELEASE` and its comment as `PRERELEASE` is not defined on master.

## Gem build
- [ ] gem build *.gemspec
- [ ] VERIFY the gem has no '.pre' version suffix.

## RSpec
- [ ] `rake spec`
- [ ] VERIFY version examples pass without failures

## Commit & Push
- [ ] `git commit -a`
- [ ] `git push origin master`
```

When merging to DESTINATION other than `master`:

```
# Post-merge Steps

Perform these steps prior to pushing to DESTINATION or the build will be broke on DESTINATION.

## Version
- [ ] Edit `lib/metasploit/concern/version.rb`
- [ ] Change `PRERELEASE` from `SOURCE_SUMMARY` to `DESTINATION_SUMMARY` to match the branch (DESTINATION) summary (DESTINATION_SUMMARY)

## Gem build
- [ ] gem build *.gemspec
- [ ] VERIFY the prerelease suffix has change on the gem.

## RSpec
- [ ] `rake spec`
- [ ] VERIFY version examples pass without failures

## Commit & Push
- [ ] `git commit -a`
- [ ] `git push origin DESTINATION`
```

* Add a 'Release Steps' comment

The 'Release Steps' are a reminder to the reviewer of the Pull Request of how to release the gem.

```
# Release

Complete these steps on DESTINATION

## `VERSION`

### Compatible changes

If your change are compatible with the previous branch's API, then increment [`PATCH`](lib/metasploit/concern/version.rb).

### Incompatible changes

If your changes are incompatible with the previous branch's API, then increment [`MINOR`](lib/metasploit/concern/version.rb) and reset [`PATCH`](lib/metasploit/concern/version.rb) to `0`.

- [ ] Following the rules for [semantic versioning 2.0](http://semver.org/spec/v2.0.0.html), update [`MINOR`](lib/metasploit/concern/version.rb) and [`PATCH`](lib/metasploit/concern/version.rb) and commit the changes.

## MRI Ruby
- [ ] `rvm use ruby-1.9.3@metasploit-concern`
- [ ] `rm Gemfile.lock`
- [ ] `bundle install`
- [ ] `rake release`
```

### Downstream dependencies

When releasing new versions, the following projects may need to be updated:

* [metasploit_data_models](https://github.com/rapid7/metasploit_data_models)
* [metasploit-credential](https://github.com/rapid7/metasploit-credential)
* [metasploit-framework](https://github.com/rapid7/metasploit-framework)
* [metasploit-pro-ui](https://github.com/rapid7/pro/tree/master/ui)
* [metasploit-pro-engine](https://github.com/rapid7/pro/tree/master/engine)
* [firewall_egress](https://github.com/rapid7/pro/tree/master/metamodules/firewall_egress)