foss/walter
foss/walter
3
0
Fork 0
Code Pull Requests Releases Activity

readme

Browse Source
This commit is contained in:
Mike Sutton 2021-10-01 02:24:36 +02:00
parent bc083c38c8
commit 9f2b6236a6
1 changed files with 3 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
README.md
View File

@ -82,10 +82,10 @@ Tell Walter where to insert its generated JavaScript in `app/views/layouts/appli
## Defining your tours ## Defining your tours
Define your tours in the `config/tours` directory corresponding to the views defined in your application. Its directory structure mirrors your application's controllers, and the tour files mirror your actions/views. (As of version 2.4.0, Walter respects controllers organized into modules.) Define your tours in the `app/tours` directory corresponding to the views defined in your application. Its directory structure mirrors your application's controllers, and the tour files mirror your actions/views. (As of version 2.4.0, Walter respects controllers organized into modules.)
``` ```
config/ app/
└── tours/ └── tours/
├── admin/ ├── admin/
│ └── articles/ │ └── articles/
@ -132,7 +132,7 @@ intro:
Walter takes care of which buttons should appear with each step: Walter takes care of which buttons should appear with each step:
* "Later" and "Continue" buttons on the first step * "Later" and "Continue" buttons on the first step
* "Exit" and "Next" buttons on intermediate steps * "Exit", "Back" and "Continue" buttons on intermediate steps
* "Done" button on the last step * "Done" button on the last step
When you specify an `attachTo` element, use the `placement` option to choose where the callout should appear relative to that element: When you specify an `attachTo` element, use the `placement` option to choose where the callout should appear relative to that element:
@ -197,101 +197,3 @@ Rails.application.configure do
end end
``` ```
## Full example
We provide a [small example app](https://github.com/actmd/walter-example) that implements Walter, so you can see it in action.
## Upgrading
### From version 2.3.0 or earlier
Walter 2.4.0 introduced an updated initializer that supports controllers organized into modules.
Rerun the generator with these options to replace the old initializer:
```
$ rails generate walter:install --skip-migration --skip-config
```
### From version 1
Walter v1 was built using Shepherd 1.8, v2 now uses Shepherd 6 – quite a jump, yes.
If you were using Walter v1, you'll want to take the following steps to upgrade:
1. Update your gem to the latest version
1. Fix your yarn dependencies to use the right versions
1. Shepherd no longer provides a set of themes. Walter maintains two of the legacy themes: default and dark. You'll want to choose one of those or migrate your theme to the new Shepherd structure.
1. Walter now exposes the entire Shepherd configuration object, so your `walter.yml` file should now fully define the `tour_options` value instead of `default_theme`
1. There's been a slight change to `initializers/walter.rb`. Replace yours with [the latest](https://github.com/actmd/walter/blob/master/lib/generators/walter/templates/initializer.rb).
If you have any trouble at all, please [submit an issue](https://github.com/actmd/walter/issues) for assistance!
## Contributing
Contributions are welcome!
Create a feature branch (using git-flow) and submit as a pull request (with a base branch of `develop`).
Everyone interacting in Walter's codebase, issue tracker, etc. is expected to follow the [Contributor Covenent Code of Conduct](https://www.contributor-covenant.org/version/1/4/code-of-conduct).
### Getting started with the source code
Walter uses `rvm` with a gemset to ensure the appropriate version of Ruby and its dependencies. Make sure that's installed before you get started.
```
~ git clone git@github.com:actmd/walter.git
Cloning into 'walter'...
~ cd walter
ruby-2.5.3 - #gemset created /Users/jon/.rvm/gems/ruby-2.5.3@walter
ruby-2.5.3 - #generating walter wrappers - please wait
~ bundle install
Bundle complete! 13 Gemfile dependencies, 73 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
~ yarn install
```
### Testing
#### Testing locally
This Rails engine contains a test app called `dummy` with controller and system tests. They'll all get run with `rails t`.
Please note that if you change anything in the `lib/generators` folder (i.e. configuration, intializer, migration) you'll need to migrate the `dummy` app accordingly.
Final testing should be done in a standalone Rails app, following the README instructions.
To install the `walter` gem with a local path:
```
gem 'walter', path: '~/Workspace/walter'
```
#### Automated testing
We use GitHub Actions to automatically test this engine with Rails 5.2, 6.0, and 6.1.
### Releasing
Create a git-flow release:
```
$ git flow release start VERSION_NUMBER
```
Edit `lib/walter/version.rb` and increase the version number.
Build the gem and push to Rubygems:
```
$ rake build
$ gem push pkg/walter-VERSION_NUMBER.gem
```
Finish the git-flow release and push to GitHub:
```
$ git flow release finish
$ git push origin develop
$ git push origin master
$ git push --tags
```