Toogle

A Rails engine web-UI to quickly toggle feature flags in GDK.

Usage

This gem was written specifically for the GitLab codebase. It relies on GitLab's Feature classes, so mounting it in any other Rails app won't work (for developing Toogle itself there is a standalone dummy app, see below).

Usage within the GitLab Development Kit

The UI is available at http://gdk.test:3000/rails/features.

Contributing

Everyone can contribute. Open issues and merge requests at https://gitlab.com/thutterer/toogle. Please make sure rake (specs and linter) passes before submitting.

There is an AGENTS.md with the conventions and architecture notes that keep this codebase simple — worth a read, and keep it accurate when you change things.

How to run it standalone

The dummy app used for testing includes fake in-memory versions of GitLab's Feature and Flipper classes (see spec/dummy/app/models/), so you can develop the engine without a GDK:

cd spec/dummy
bin/rails server

Then open http://localhost:3000/toogle. Toggled state lives in memory and resets on restart.

To test your changes inside a real GDK, point GitLab's Gemfile at your local checkout:

gem 'gdk-toogle', path: '~/Code/toogle', require: 'toogle'

How to run tests and linting

Run rake to run both the specs and the standard linter. They are also available separately as rake spec and rake standard (use rake standard:fix to autoformat).

To lint automatically before each commit, enable the bundled git hook once:

git config core.hooksPath .githooks

The system specs in spec/system use headless Firefox by default. Set CAPYBARA_DRIVER to any registered Capybara driver to switch, e.g. if you don't have Firefox or only a Snap-installed one (incompatible with geckodriver):

CAPYBARA_DRIVER=selenium_chrome_headless bundle exec rspec

How to cut a release

  1. Bump Toogle::VERSION in lib/toogle/version.rb.
  2. Add an entry to CHANGELOG.md.
  3. Commit, then tag: git tag vX.Y.Z && git push --tags.
  4. Build and push the gem: rake build then gem push pkg/gdk-toogle-X.Y.Z.gem.
  5. Bump the version constraint in GitLab's Gemfile to pick it up.

Keep Ruby and gem versions at or below what GitLab itself runs (see AGENTS.md).

Tech stack

One design goal of this little Rails engine was to keep it free of any dependencies, that GitLab uses today. Because, tomorrow we might decide to ditch one or the other tech we use today, and Toogle shouldn't break just because GitLab removes sassc, as an example (that actually happened during development).

That's why Toogle only depends on the bare basics: rails, sprockets and haml.

Javascript

Toogle uses Alpine.js from a <script> tag so it does not use or depend on our Vue.js usage or any bundler. Alpine is very similar to Vue, so it's really easy to pick up. Give it a try!

CSS

Toogle uses native unprocessed CSS to not depend on any specific preprocessor. Modern CSS is awesome, and all modern browsers support things like nested selectors today.

For theming and dark mode, it uses CSS variables and HSL colors, which makes it super easy to switch from light to dark by just changing the variable that makes up the Lightness. Check it out!

License

The gem is available as open source under the terms of the MIT License.