Refactor rebar3_hex_publish and support --app on publish

[starbelly]

This commit is mostly a refactor of rebar3_hex_publish. The following rationale is provided for the refactoring:

Refactor rationale

• Avoid going down paths and branches when we don't have to
  • If we only publish docs as an example, there's no need to validate the app, build up a package, etc.
• Raising provider errors vs passing provider errors around
  • This is for all intents and purposes a command line application, as such it doesn't need to be treated like a general purpose library.
  • More importantly, by raising errors we can ensure our error makes it back up to the caller (rebar3) and we get the error in our format_error/1 callback.
  • The above is important because we never want to crash in such a user facing application simply because we failed to handle an error case or properly propogate it up the stack ourselves.
  • Finally per raising instead of returning errors we end up with leaner code..
• Splitting up big functions into smaller functions so that we may rely less on "integration" tests and can focus more on unit tests (e.g, tests with less mecking, more stubbing, and no fake servers).
• To establish a pattern going forward for all other tasks (both existing and forth coming).

Changes

• Added ?RAISE_ERROR macro, raises a ?PROVIDER_ERROR
• Added assert_valid_app/2 which raises when the app is not deemed valid
• Move app validation up the stack closer to the entry point
• Refactored publish/* into publish_package/3 and publish_docs/3
• Added build_package/3
• Added create_tarball/2
• Changed task_state/1 to put project_apps in task() and to not set the current_app

TODO:

• [x] Update rebar3_hex_cut to work with refactored functions
• [x] Fix dialyzer warnings
• [x] QA against a local hex instance

[starbelly]

This is open for review now. The actual set of changes is small if you don't include deletion of stubs. One thing this PR lacks is testing for umbrellas, but we didn't have this already. We do need this, but it might require re-working some of the integration test helpers a good bit, and I didn't want this PR to grow anymore.

More refactoring and splitting out pure functions into other modules should be a part of that, this should happen in a subsequent PR. More tests need to be added as well of course, but that should also be done as another PR IMO.

I'd like to get this one through and then focus on the rest of the breaking changes in other tasks (and the refactoring of those modules) at this point.

[paulo-ferraz-oliveira]

Added ?RAISE_ERROR macro, raises a ?PROVIDER_ERROR

I think you mean ?RAISE.

Refactored publish/* into publish_package/3 and publish_docs/3

I think you mean /4 on both instances.

Added create_tarball/2

I think you mean /1.

(not trying to nitpick, just want to make sure the changelog is proper, if you ever have one)

[paulo-ferraz-oliveira]

Did none of this imply changes to the README? Or will this come at a later date?

[starbelly]

Added ?RAISE_ERROR macro, raises a ?PROVIDER_ERROR

I think you mean ?RAISE.

Correct, will amend.

Refactored publish/* into publish_package/3 and publish_docs/3

I think you mean /4 on both instances.

Correct, will amend.

Added create_tarball/2

I think you mean /1.

Correct, will amend.

(not trying to nitpick, just want to make sure the changelog is proper, if you ever have one)

No worries, and yes, I have been thinking we need to start keeping a changelog. There's at least two ways to do that. Systematically (requires everyone to do commits in the same format) or we just cobble it together and prepend on each release, but yeah fully agree none the less.

[starbelly]

Did none of this imply changes to the README? Or will this come at a later date?

Later. There's still a good number of PRs that need to happen first, but it shall be updated. We'll also have to update the docs. That brings up another issue, which I will make an issue for.

[paulo-ferraz-oliveira]

No worries, and yes, I have been thinking we need to start keeping a changelog. There's at least two ways to do that. Systematically (requires everyone to do commits in the same format) or we just cobble it together and prepend on each release, but yeah fully agree none the less.

I've seen a bunch of ways this is done, in the past, in other projects.

1. a CHANGELOG.md maintained by hand,
2. a note on the GitHub releases page, also by hand,
3. a CHANGELOG.md maintained more or less automatically,
4. commits that follow a standard (very very easy to get wrong, unless automatically checked upon push - and am sure this would make some uncomfortable to contribute).

I prefer 3. If the PR titles are proper (I wouldn't go as deep as commits, since mostly we're going to squash them to 1 per pull request - right?), it should be fairly easy to generate one. And it doesn't even need a lot of discipline (unless the releaser wants to have as little trouble as possible), since you can always generate it, tweak the titles - if not readable -, then generate again. (to be discussed in another forum, perhaps)

[starbelly]

@tsloughter ping for review