cornelius/yes_ship_it

The ultimate release script

Yes, ship it!

The ultimate release script

Whenever the answer is "Yes, ship it!" you will need yes_ship_it, this tool. It is the ultimate helper in releasing software.

Shipping software is not an action. It's a state of mind. yes_ship_it helps you to make sure that reality matches this state of mind. It won't fix the bugs in your software, it doesn't create the tests which would need to be there, it doesn't write your release notes. It does make sure that your good engineering is delivered to your users with zero cost.

The approach of yes_ship_it is different from the typical release script. It doesn't define a series of steps which are executed to make a release. It defines a sequence of assertions about the release, which then are checked and enforced.

This works in a way you could describe as idempotent, which means you can execute it as many times as you want, the result will always be the same, regardless of the initial state. That means the whole process is robust against errors which happen during releasing, it transparently copes with manual tweaks and changes, and it works on old releases just as well as on new releases.

After successfully running yes_ship_it your release will have shipped, and the state of the world will reflect the state of your mind.

Assumptions

yes_ship_it assumes that you develop your software in a version control system and keep at least some minimal state of releases there. This could just be a tag. It also assumes that you are able to run yes_ship_it from the command line and have some access to the systems which are needed to complete the things part of a release.

How to run it

Go to the checkout of the sources of your software. Check that there is a file called yes_ship_it.conf there. Run yes_ship_it. Done.

Configuration

The central configuration of what happens when you run yes_ship_it is the yes_ship_it.conf file in the root directory of the sources of your software. There you define the sequence of assertions which are run through for making sure that the release is happening in the way you intend. yes_ship_it comes with some predefined sequences of assertions you can simply reuse.

The format of yes_ship_it.conf uses YAML. A minimal yes_ship_it.conf file could look like this:

include:
  standard_rubygem

A more detailed configuration could look like this:

assertions:
  - ci_green
  - release_notes
  - version_number
  - gem_built
  - release_tagged
  - gem_pushed

There can be more configuration on a general level or the level of the assertions to adjust to specific needs of each software project. There also can be other or additional assertions.

Extending yes_ship_it

Many software projects will have specific needs for their releases. These can be broken down and reflected in additional assertions. Adding assertions is easy. There is a well-defined API for it.

You can extend yes_ship_it by writing local assertions as plugins. Use the command yes_ship_it plugin to generate and manage them.

While plugins can be useful for very special assertions or as a start for new ones, it would be great to generalize them and ship them with yes_ship_it. This will maximize the value for the community of people who ship software. The project is very open to include new assertions. Just submit a pull request. yes_ship_it will ship it with the next release.

Testing

Testing a tool such as yes_ship_it is not easy because its prime functionality is to interact with other systems and publish data. There are unit tests for the code. There also are integration tests which work in a virtual environment which fakes the services yes_ship_it interacts with. It uses the pennyworth tool to manage the virtual environment and make them accessible in a convenient way from the RSpec tests.

Further documentation

You get basic documentation from the tool itself by executing yes_ship_it help. There also is a simple man page with some pointers.

The main documentation with details about different scenarios how yes_ship_it can be used is maintained in the Wiki. You are welcome to contribute there.

Users

There is a list of users of yes_ship_it. I'm happy to add you there. Just send me a pull requests for the USERS.md file.

License

yes_ship_it is licensed under the MIT license.

Contact

If you have any questions or comments, please don't hesitate to get in touch with me: Cornelius Schumacher [email protected].

yes_ship_it's Issues

Take release date from tag

The yes_it_shipped assertion should take the release_date_time attribute from the date of the tag and not use Time.now.

Make sure that released code has been pushed

Add a code_pushed assertion, which checks that the code has been pushed to the git server, so that the release actually is publicly available.

Don't show output of pushing tag

pushed_tag prints the git output of pushing the tag to the console. Hide it instead.

Full release test

The current system tests are only testing a partial release. It would be nice to have a test which covers a full release including all assertions.

Document dependencies from each assertion and improve changelog assertion

i was trying to use the change log assertion for a project. 🌞

The issue i encountered is that the changelog assertion without the 'version' or 'tag' just assert that the file exists. ( we might think about to improve it better).

Another issue that i found also is that the version assertion is hardcode to ruby version.rb https://github.com/cornelius/yes_ship_it/blob/master/assertions/version.rb#L3.

For improving changelog, i think a good assertion would from my pov to rely more on the git tag.
Like check if the project have tag '0.0.1' and check if we have this in changelog
Should maybe the merge of tag and changelog be considered? or how we can avoid intra-deps of assertions. Imho i would suggest to have a assertion that doesn't depend from others (meaning we merge tag and other if needed). but it's a suggestion based on first experience i had with the tool, maybe it the design, in this case we should document better the dependencies.

Move all code calling git to `Git` class

All calls to git should be encapsulated by the Git class, so that there is consistent error handling and no duplicated code.

Use `Executor` for all HTTP calls in `check` method

Some assertions have code in their check methods which is directly using RestClient to do HTTP calls. This should be moved to use Executor, so that all calls are done in a consistent way and errors are handled consistently.

Assert that release details have been pushed to GitHub

Make sure that release details such as the change log have been uploaded to GitHub. (See e.g. https://github.com/cornelius/yes_ship_it/releases).

Find a nicer way to implement dry run

The assert method takes a boolean dry_run parameter which controls, if modifications are actually done or it's just shown what would be done.

When implementing assertions it's up to the developer to do the right thing there and implement and respect the option. It would be nicer, if this would be encapsulated by the API somehow, so that the developer would be guided to do the right thing or it would even be enforced by the framework.

Assertion: Jenkins

Add an assertion which talks to Jenkins and checks that the git revision to be released has successfully passed all tests.

`yes_ship_it` hangs, when `gem push` asks for credentials

When the user hasn't logged in to rubygems.org yet, the gem push command is asking for credentials on the command line. This makes yes_ship_it just hang without any message.

It should expose the prompt to put in the credentials or fail with an error and hint how to login instead.

Create templates for required files with `init`

The init command should look, if required files such as CHANGELOG.md are there and create templates to get started, if they are missing.

Update wiki with ruby gem config info

Support git checkouts under different names than the default name

If you clone with a custom name for the local directory, the project name should still be determined correctly.

Assertion: build

Add an assertion which builds things (binaries, libraries, etc.) The approach would be to just call the exiting build system (e.g. rake build).

Tell users about yes_it_shipped

The init command adds a yes_it_shipped assertion which publishes the release at the "yes it shipped" web site.

It would be nice to tell users that the default config generated by init will do that, so that they are not surprised by yes_ship_it talking to an external web app.

Add service to collect release notifications

It would be nice to have a central service to collect all releases done by yes_ship_it. I imagine a very simple web site which lists new releases of software projects as a kind of news ticker, very basic design, showing name, date, version, and a link to the project for each release, smoothly scrolling through history, possibly with some search or filter functions.

To implement this, we should add a standard release_notification_sent assertion, which takes care of the release being pushed to the central yes_ship_it release collection service. The assertion would make sure that the basic data of the release is sent to the server.

The server should implement a simple POST call which takes the URL to the repo of the project, an additional URL to the yes_ship_it.conf file, a URL to the release, the name, version, and release date, as parameters, and adds this as an entry to the data base. The URLs can be used to check that the project and the release actually exist.

The server should also implement a GET call to check, if a release already is known to the server.

Assertion: Update GitHub page

Add an assertion to do updates to the GitHub page hosted in the gh-pages. This assertion needs to take some custom code to do the actual update, but it could generalize the handling of the branch itself.

Handle error output in a more graceful way

When some tool called by an assertion puts out something on stderr, e.g. the dependency warnings of gem build, it's simply mixed into the output of yes_ship_it. This doesn't look very nice as it breaks the "one assertion, one line" assumption.

Here is an example:

Shipping...

Checking release branch: master
Checking working directory: clean
Checking version number: 0.0.5
Checking change log: CHANGELOG.md
Checking tag: fail
Checking built gem: fail
Checking published gem: fail
Checking pushed tag: fail
Checking pushed code: fail
Checking pushed to yes-it-shipped: fail

Asserting tag: v0.0.5
Asserting built gem: WARNING:  open-ended dependency on given_filesystem (>= 0.1.2, development) is not recommended
  if given_filesystem is semantically versioned, use:
    add_development_dependency 'given_filesystem', '~> 0.1', '>= 0.1.2'
WARNING:  open-ended dependency on cli_tester (>= 0.0.2, development) is not recommended
  if cli_tester is semantically versioned, use:
    add_development_dependency 'cli_tester', '~> 0.0', '>= 0.0.2'
WARNING:  See http://guides.rubygems.org/specification-reference/ for help
httpotemkin-0.0.5.gem
Asserting published gem: httpotemkin-0.0.5.gem
Asserting pushed tag: Counting objects: 15, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (14/14), done.
Writing objects: 100% (15/15), 1.65 KiB | 0 bytes/s, done.
Total 15 (delta 10), reused 0 (delta 0)
To [email protected]:cornelius/httpotemkin
 * [new tag]         v0.0.5 -> v0.0.5
v0.0.5
Asserting pushed code: Total 0 (delta 0), reused 0 (delta 0)
To [email protected]:cornelius/httpotemkin
   b0c8227..855369d  master -> master
pushed
Asserting pushed to yes-it-shipped: 
Ran into an error. Stopping shipping.

Don't push code, when released code is already pushed

When the released code is already pushed, but there are additional commits which haven't been pushed the pushed_code assertion pushes the code, even when it's not needed. It should properly check, if the code belonging to the release is not pushed, not if any code is not pushed.

Support for gem names different from project names

We need to check that we use the right names everywhere, when the gem is named differently from the project.

Option to run on an old release

To check old releases it would be great to be able to tell yes_ship_it to run on a given version number. This could be used to just verify old releases or to add additional artifacts. As changing the past is usually not a good idea, the default for old releases should be to run all the checks, but don't try to change anything (basically the dry run). An option should allow to do the changes, though (--assert maybe?).

Better signalling of assertion check results

At the moment check returns a string which is printed to the user when successfull and nil when the check failed (but no error happened). This could be made more expressive by returning an AssertionStatus object which encapsulates the results in the way the calling code needs it.

Adapt assertion to create RPM

We need to make it possible to call a rake build:prepare to prepare the build directory, which is needed for local builds as well as for release builds in the build service.

This does:

• Spec file generation
• Copy rpm lint file
• Update .changes file

Additionally we have to make sure that we cover what is in the Rake task osc:commit, which overlaps with the assertions to create a gem and to push to the build service.

Don't overwrite existing configuration with `init`

The init command should check, if a configuration is already there and not overwrite it if there is.

add a parameter to "yes_it_shipped" assertion to overwrite the default server

Even thought it may be nice to have a centralized "yes_it_shipped" server to see all projects that use it, it is convenient to be able to overwrite that default by adding a parameter.

Use cases:

• testing yes_ship_it
• private projects with its own "yes_it_shipped" hosting

Check if code is in git which hasn't been released yet

If there are additional commits in git after the last release has been done (which corresponds to the version number in git), yes_ship_it only checks that the last release is ok, but doesn't give any indication that there is unreleased code.

Either the version assertion should check that, or there should be a separate assertion.

Assertion plugins

For running project-specific assertions we need some kind of plugin mechanism.

We could check for ruby files in a local yes_ship_it.d directory and treat them just as all the built-in assertions. Then the config could also use the local assertions.

In general it would be nice to try to move as much stuff to the built-in assertions. So generalizing and parametrizing local assertions could make them suitable for inclusion in the tool itself.