README.md in seam-1.1.3 vs README.md in seam-2.0.0a1
- old
+ new
@@ -1,166 +1,166 @@
-# Seam
+# Seam Ruby SDK
-Simple workflows in Ruby.
+[](https://rubygems.org/gems/seam)
+[](https://github.com/seamapi/ruby-next/actions/workflows/check.yml)
-## Usage
+SDK for the Seam API written in Ruby.
-Seam is meant for situations where you want to take some entity (user, order, ec.) through a long-running process that is comprised of multiple steps.
+## Description
-For example, if you want every new user a "hello" email after signup, then wait a few days, and then send a "gone so soon?" email if they haven't signed in again.
+TODO
-This gem provides some simple tools for building and executing this process.
-It provides a way to define the process, break it up into separate components, and then send entities through the process.
+## Installation
-####Define a workflow####
+Add this as a dependency to your project using [Bundler] with
-To start, define a workflow.
+```
+$ bundle add seam
+```
-````
-flow = Seam::Flow.new
-flow.send_order_to_warehouse
-flow.wait_for_order_to_be_shipped wait_up_to: 7.days
-flow.send_shipping_email email_template: 'shipping_7'
-flow.mark_order_as_fulfilled
-````
+[bundler]: https://bundler.io/
-A flow will convert any method call you make into a step that has to be completed.
+## Development and Testing
-You can also pass a hash to the method, which will be saved for later.
+### Quickstart
-````
-flow.wait_for_order_to_be_shipped wait_up_to: 7.days
-````
+```
+$ git clone https://github.com/seamapi/ruby-next.git
+$ cd ruby-next
+$ bundle install
+```
-####Starting an instance of the flow####
+Run the command below
-Starting an instance of the flow is done with "start":
+```
+$ bundle exec rake
+```
-````
-flow.start order_id: '1234'
-````
+Open an interactive ruby console with
-An instance of this effort was created and saved in whatever persistence is being used (in-memory by default).
+```
+$ bundle exec rake
+```
-This effort will start at the first step (send_order_to_warehouse) and then progress through the steps as they are completed.
+Primary development tasks are defined as [rake] tasks in the `Rakefile`
+and available via `rake`.
+View them with
-"start" also returns the effort that was created, and it will look like this:
+```
+$ bundle exec rake -T
+```
-````
-<Seam::Effort
- @completed_steps=[],
- @history=[],
- @complete=false,
- @id="1ecc4cbe-16af-45f6-8532-7f37493ec11c",
- @created_at=2013-08-20 22:58:07 -0500,
- @next_execute_at=2013-08-20 22:58:07 -0500,
- @next_step="send_order_to_warehouse",
- @flow={"steps"=>[{"name"=>"send_order_to_warehouse", "type"=>"do", "arguments"=>{}}, {"name"=>"wait_for_order_to_be_shipped", "type"=>"do", "arguments"=>{}}, {"name"=>"send_shipping_email", "type"=>"do", "arguments"=>{}}, {"name"=>"mark_order_as_fulfilled", "type"=>"do", "arguments"=>{}}]},
- @data={"order_id"=>"1234"}>
-````
+[rake]: https://ruby.github.io/rake/
-So we have a unique instance of this flow and the instance has been saved in the database. The first step to be executed for this instance is "send_order_to_warehouse", so let's create a worker for this step.
+### Source code
-####Defining workers for each step####
+The [source code] is hosted on GitHub.
+Clone the project with
-A workflow is comprised of steps, and each step needs a worker. Each worker will execute whatever it was meant to do, and then either:
+```
+$ git clone git@github.com:seamapi/ruby-next.git
+```
-1. Pass the workflow instance to the next step on the process, or
-2. Delay the step execution for a later date, or
-3. End the entire workflow process for the instance.
+[source code]: https://github.com/seamapi/ruby-next
-Since send_order_to_warehouse is the first step in this workflow, let's build the worker for it first:
+### Requirements
-````
-class SendOrderToWarehouseWorker < Seam::Worker
- def process
- # the current workflow instance is available as "effort"
- order = Order.find effort.data['order_id']
- warehouse_service.send order
+You will need [Ruby] with [Bundler].
- # by default, if this worker completes with no error the workflow instance will be sent to the next step
- end
-end
-````
+Be sure that all commands run under the correct Ruby version, e.g.,
+if using [rbenv], install the correct version with
-If you name your class as a camel-case version of the step, Seam will automatically bind up the worker to the step.
+```
+$ rbenv install
+```
-To execute the worker, use:
+Install the development dependencies with
-````
-SendOrderToWarehouse.execute_all
-````
+```
+$ bundle install
+```
-This method will look for all workflow instances that are currently ready for the step in question.
+[bundler]: https://bundler.io/
+[ruby]: https://www.ruby-lang.org/
+[rbenv]: https://github.com/rbenv/rbenv
-####Progressing through the workflow####
+### Publishing
-By default, steps are considered as being completed when the worker completes successfully. There might be times where you don't want to go quickly, like the next step in this example:
+New versions are created with [gem release].
-````
-class WaitForOrderToBeShippedWorker < Seam::Worker
- def process
- effort.data["shipping_status"] = # some method that returns the shipping status
- unless effort.data["shipping_status"] == "shipped"
- try_again_in 4.hours
- end
- end
-end
-````
+#### Automatic
-"try_again_in" can be used to signal that the step has not been completed and should be retried later.
+New versions are released automatically with [semantic-release]
+as long as commits follow the [Angular Commit Message Conventions].
-"eject" can also be used to signify that the entire workflow should be stopped, like so:
+[Angular Commit Message Conventions]: https://semantic-release.gitbook.io/semantic-release/#commit-message-format
+[semantic-release]: https://semantic-release.gitbook.io/
-````
-class WaitForOrderToBeShippedWorker < Seam::Worker
- def process
- effort.data["shipping_status"] = # some method that returns the shipping status
- if effort.data["shipping_status"] == "cancelled"
- eject # no need to continue!
- end
- end
-end
-````
+#### Manual
-####History####
+Publish a new version by triggering a [version workflow_dispatch on GitHub Actions].
+The `version` input will be passed to the `--version` option of `gem bump`.
-As workflow instances progress through each step, the history of every operation will be stored. A history of the "data" block before and after each step run is also stored.
+This may be done on the web or using the [GitHub CLI] with
-The history is available through:
+```
+$ gh workflow run version.yml --raw-field version=<version>
+```
-````
-effort.history
-````
+[gem release]: https://github.com/svenfuchs/gem-release
+[GitHub CLI]: https://cli.github.com/
+[version workflow_dispatch on GitHub Actions]: https://github.com/seamapi/ruby-next/actions?query=workflow%3Aversion
-####Waiting####
+## GitHub Actions
-Seam comes with a default worker for waiting. It can be defined by calling "wait" on a flow, like this.
+_GitHub Actions should already be configured: this section is for reference only._
-````
-flow = Seam::Flow.new
-flow.send_order_to_warehouse
-flow.wait 2.days
-flow.check_if_the_order_has_been_fulfilled
-````
+The following repository secrets must be set on [GitHub Actions]:
-## Installation
+- `RUBYGEMS_API_KEY`: RubyGems.org token for publishing gems.
-Add this line to your application's Gemfile:
+These must be set manually.
- gem 'seam'
+### Secrets for Optional GitHub Actions
-And then execute:
+The version, format, generate, and semantic-release GitHub actions
+require a user with write access to the repository.
+Set these additional secrets to enable the action:
- $ bundle
+- `GH_TOKEN`: A personal access token for the user.
+- `GIT_USER_NAME`: The GitHub user's real name.
+- `GIT_USER_EMAIL`: The GitHub user's email.
+- `GPG_PRIVATE_KEY`: The GitHub user's [GPG private key].
+- `GPG_PASSPHRASE`: The GitHub user's GPG passphrase.
-Or install it yourself as:
+[github actions]: https://github.com/features/actions
+[gpg private key]: https://github.com/marketplace/actions/import-gpg#prerequisites
- $ gem install seam
-
## Contributing
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+Please submit and comment on bug reports and feature requests.
+
+To submit a patch:
+
+1. Fork it (https://github.com/seamapi/ruby-next/fork).
+2. Create your feature branch (`git checkout -b my-new-feature`).
+3. Make changes.
+4. Commit your changes (`git commit -am 'Add some feature'`).
+5. Push to the branch (`git push origin my-new-feature`).
+6. Create a new Pull Request.
+
+## License
+
+This Ruby gem is licensed under the MIT license.
+
+## Warranty
+
+This software is provided by the copyright holders and contributors "as is" and
+any express or implied warranties, including, but not limited to, the implied
+warranties of merchantability and fitness for a particular purpose are
+disclaimed. In no event shall the copyright holder or contributors be liable for
+any direct, indirect, incidental, special, exemplary, or consequential damages
+(including, but not limited to, procurement of substitute goods or services;
+loss of use, data, or profits; or business interruption) however caused and on
+any theory of liability, whether in contract, strict liability, or tort
+(including negligence or otherwise) arising in any way out of the use of this
+software, even if advised of the possibility of such damage.