Skip to content

Commit acf5237

Browse files
adamcreekroadadamcreekroad
committed
Merge branch 'edge' into issue-215
2 parents 11bfcdd + 19fc204 commit acf5237

23 files changed

Lines changed: 592 additions & 235 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 67 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ If you're new to Hyperstack but have experience with Ruby (and Rails) and would
55
that way you understand the basic capabilities and lingo of Hyperstack.
66

77
Next would be to start an experimental project that's based on the *edge* Hyperstack codebase.
8-
If you just want to build a website with Hyperstack without contributing to Hyperstack itself you're better of sticking to released versions of Hyperstack.
8+
If you just want to build a project with Hyperstack without contributing to Hyperstack itself you're better of sticking to released versions of Hyperstack.
99
But presuming you do want to contribute you can change you `Gemfile` in the following way to get your project on *edge*.
1010

1111
```ruby
@@ -27,22 +27,45 @@ The *edge* branch is the latest work in progress, where specs (automated tests)
2727
The difference between *edge* and *master*, is that *master* guarantees that all specs across all gems pass, plus *master* is the branch from which new versions are released.
2828

2929
With this configuration you can track development of Hyperstack itself and discuss changes with the other developers.
30-
It's the basic starting point from which you can make different types of contributions listed below under the separate headings.
3130

32-
## If you would like to contribute code to Hyperstack
31+
In the following sections we explain how to make different types of contributions.
32+
- Contributing code to Hyperstack
33+
- Running tests for your code
34+
- Adding your own tests
35+
- Improving the Hyperstack documentation
36+
- If you think you can improve the website
37+
- When you find a possible bug
38+
- Fixing a bug
39+
40+
## Contributing code to Hyperstack
3341

3442
With the `Gemfile` configuration above you can track Hyperstack development. But you can't contribute code.
3543

3644
For that you need to `git clone https://github.com/hyperstack-org/hyperstack.git`
3745
Cd into the directory `cd hyperstack`
3846
And change to the *edge* branch: `git checkout edge` (*edge* is the default branch but just to be sure).
3947

40-
Now you're free to fix bugs and create new features.
41-
Reconfigure the `Gemfile` of your website project with a [filesystem path](https://bundler.io/gemfile.html) to create a local development environment.
48+
This gives you a local copy of the Hyperstack codebase on your system.
49+
You will have to reconfigure the `Gemfile` of your own website project with a [filesystem path](https://bundler.io/gemfile.html) so it uses this local Hyperstack copy.
50+
4251
```
43-
TODO: Actually provide an example Gemfile..
52+
gem 'rails-hyperstack', path: '~/path/to/hyperstack/ruby/rails-hyperstack'
53+
gem 'hyper-component', path: '~/path/to/hyperstack/ruby/hyper-component'
54+
gem 'hyper-i18n', path: '~/path/to/hyperstack/ruby/hyper-i18n'
55+
gem 'hyper-model', path: '~/path/to/hyperstack/ruby/hyper-model'
56+
gem 'hyper-operation', path: '~/path/to/hyperstack/ruby/hyper-operation'
57+
gem 'hyper-router', path: '~/path/to/hyperstack/ruby/hyper-router'
58+
gem 'hyper-state', path: '~/path/to/hyperstack/ruby/hyper-state'
59+
gem 'hyperstack-config', path: '~/path/to/hyperstack/ruby/hyperstack-config'
60+
gem 'hyper-trace', path: '~/path/to/hyperstack/ruby/hyper-trace', group: :development
61+
#gem 'hyper-store', path: '~/path/to/hyperstack/ruby/hyper-store' # Extra (legacy?)
4462
```
45-
And if your improvements could be interesting to others then push it to Github and create a pull request.
63+
64+
Or use `bundle config local.GEM_NAME /path/to/hyperstack` as described [here](https://rossta.net/blog/how-to-specify-local-ruby-gems-in-your-gemfile.html). But I would recommend the Gemfile with a local path approach.
65+
Use `bundle config --delete local.GEM_NAME` to remove a `bundle config local` configuration.
66+
67+
This setup provides a local Hyperstack development environment. You're now able to fix bugs and create new features within the Hyperstack code itself.
68+
If your improvements could be interesting to others then push it to Github and create a pull request.
4669
Then keep reminding the existing developers that you would like your code pulled into the Hyperstack repository.
4770
When they find the time to look at it and like your code they will kindly ask you to also write some specs before your code is merged. That's a good thing, your code is considered valuable, but does require those tests.
4871
Please understand that your code can also be rejected because it has security issues, is slow, hard to maintain or buggy (among other things).
@@ -54,7 +77,37 @@ But Hyperstack and Opal are quite happily pushing boundaries, so we might like y
5477

5578
Hyperstack's [license is MIT](https://github.com/hyperstack-org/hyperstack/blob/edge/LICENSE). All code contributions must be under this license. If code is submitted under a different open source license then this must be explicitly stated. Preferably with an explanation why it can't be MIT.
5679

57-
## If you would like to improve the Hyperstack documentation
80+
### Running tests for your code
81+
82+
Hyperstack has a comprehensive automated test system. Changes to code must be accompanied with the necessary tests.
83+
This is how you setup the test environment on your local development system:
84+
85+
- You do the `git clone https://github.com/hyperstack-org/hyperstack.git` as before.
86+
- Now you enter the gem you would like to run the tests for. Lets say you change directory to the hyper-model gem `cd ~/path/to/hyperstack/ruby/hyper-model`
87+
- Optionally but recommended: Create a RVM environment by adding the `.ruby-gemset` and `.ruby-version` files, run `cd .` to reload RVM.
88+
- Install bundler `gem install bundler` then run `bundle install` to pull in the gems needed for testing.
89+
- Then you have to setup the test environment by running `rake spec:prepare`, this creates the test database and tables.
90+
91+
After this call `rspec spec` to run the tests.
92+
93+
If all test pass you know your changes to the Hyperstack code did not break any existing functionality.
94+
Please understand that tests can sometimes be flaky, re-run tests if needed. Sometimes it's just the phase of the moon.
95+
96+
### Adding your own tests
97+
98+
Cleaning up and improving the existing tests is a great and "safe" way to contribute and get experience with the Hyperstack codebase.
99+
100+
**TODO:** Pointers about directory structure.
101+
102+
- Test one thing at a time, don't write one large test.
103+
- Check the before state, call the code you want to test, check if the before state has changed to the expected state.
104+
- Test the interface, the internals of the implementation should keep some flexibility.
105+
- Watch out with testing things that use Date/Time, you don't want your test to fail when it's run on the 29th of February or when run in a different timezone.
106+
- Don't check if `string1.include?(string2)` if string2 can be an empty string, like "". As that would pass.
107+
- Tests are a development tool, flaky or slow tests that don't cover enough have a negative value.
108+
- Test your feature with different types of input (nil, empty string, empty array, false, zero, negative dates). Don't test with every day of the year if it exesersizes the same codepath as with the other dates.
109+
110+
## Improving the Hyperstack documentation
58111

59112
Each page on [the website](https://hyperstack.org) has an ***Improve this page*** button which will allow you to edit the underlying markdown file on Github and create a ***pull request***. This is to make it as easy as possible to contribute to the documentation.
60113
And make small fixes quickly.
@@ -69,19 +122,19 @@ The website's code can be found in [this repository](https://github.com/hypersta
69122
By running `git clone https://github.com/hyperstack-org/website.git` you can check out your own copy.
70123
Please note that this repository does not contain the documentation. The website pulls the most recent markdown files from the *edge* hyperstack repository.
71124

72-
Before you write code to change the website, please create an issue describing your plans and reach out to us in the Gitter chat. Our goal for this site is that it acts as a showcase for all that Hyperstack can do, so your creativity is very welcome.
125+
Before you write code to change the website, please create an issue describing your plans and reach out to us in Slack chat. Our goal for this site is that it acts as a showcase for all that Hyperstack can do, so your creativity is very welcome.
73126

74-
## If you found a possible bug
127+
## When you find a possible bug
75128

76-
You can ask on [gitter chat](https://gitter.im/ruby-hyperloop/chat) if you're making a mistake or actually found a bug.
77-
Also check the GitHub issue list and if you don't find it mentioned there, please create an issue.
129+
You can ask on [Slack chat](https://hyperstack-org.slack.com) if you're making a mistake or actually found a bug. (get a account via the "Join Slack" button on the [homepage](https://hyperstack.org))
130+
Also check the [GitHub issue list](https://github.com/hyperstack-org/hyperstack/issues) and if you don't find it mentioned there, please create an issue.
78131
If you can reproduce the problem in a branch you push to GitHub we will love you even more.
79132

80133
We also have a [feature matrix](https://github.com/hyperstack-org/hyperstack/blob/edge/docs/feature_matrix.md), which is an attempt to list known issues and the current status.
81134
Having people expanding and maintaining this table would be excellent.
82135

83-
## If you would like to fix a bug
136+
## Fixing a bug
84137

85-
Please ask in [gitter chat](https://gitter.im/ruby-hyperloop/chat) if you need pointers. There is always tons to do so we would appreciate the help.
138+
Please ask in [Slack chat](https://hyperstack-org.slack.com) if you need pointers. There is always tons to do so we would appreciate the help.
86139
You can see the list of GitHub issues labelled '[Help Wanted](https://github.com/hyperstack-org/hyperstack/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)'
87140
or look at the [feature matrix](https://github.com/hyperstack-org/hyperstack/blob/edge/docs/feature_matrix.md) for things that have the status 'bugged'.

‎install/rails-webpacker.rb‎

Lines changed: 36 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
# Hyperstack
2-
WITH_PRERENDERING = true
32

43
# ----------------------------------- Commit so we have good history of these changes
54

@@ -17,7 +16,8 @@
1716

1817
# ----------------------------------- Ensure Sqlite has a valid version
1918

20-
gsub_file 'Gemfile', /gem\s+'sqlite3'(?!,\s+'.*')\n/, "gem 'sqlite3', '~> 1.3.6'\n"
19+
# gsub_file 'Gemfile', /gem\s+'sqlite3'(?!,\s+'.*')\n/, "gem 'sqlite3', '~> 1.3.6'\n"
20+
# gsub_file 'Gemfile', /gem\s+'sqlite3'(?!,\s+'.*')\n/, "gem 'pg'"
2121

2222
# ----------------------------------- Create the folders
2323

@@ -60,7 +60,8 @@ class ApplicationRecord < ActiveRecord::Base
6060
# the presence of this file prevents rails migrations from recreating application_record.rb
6161
# see https://github.com/rails/rails/issues/29407
6262
63-
require 'models/application_record.rb'
63+
# BH - I am not sure this is right
64+
# require 'models/application_record.rb'
6465
CODE
6566

6667
# ----------------------------------- Create the Hyperstack config
@@ -90,6 +91,26 @@ def self.on_error(operation, err, params, formatted_error_message)
9091
end if Rails.env.development?
9192
CODE
9293

94+
# ----------------------------------- Create thyperstack.js
95+
96+
file 'app/javascript/packs/hyperstack.js', <<-CODE
97+
// Import all the modules
98+
import React from 'react';
99+
import ReactDOM from 'react-dom';
100+
// for opal/hyperloop modules to find React and others they must explicitly be saved
101+
// to the global space, otherwise webpack will encapsulate them locally here
102+
global.React = React;
103+
global.ReactDOM = ReactDOM;
104+
CODE
105+
106+
# ----------------------------------- View template
107+
108+
inject_into_file 'app/views/layouts/application.html.erb', before: %r{<%= javascript_include_tag 'application', 'data-turbolinks-track': 'reload' %>} do
109+
<<-CODE
110+
<%= javascript_pack_tag 'hyperstack' %>
111+
CODE
112+
end
113+
93114
# ----------------------------------- Add a default policy
94115

95116
file 'app/policies/application_policy.rb', <<-CODE
@@ -109,102 +130,32 @@ class Hyperstack::ApplicationPolicy
109130
ApplicationRecord.regulate_scope :all
110131
end unless Rails.env.production?
111132
# don't forget to provide a policy before production...
112-
raise "You need to define a Hyperstack policy for production" if Rails.env.production?
133+
::Rails.logger.debug("WARNING: You need to define a Hyperstack policy for production") if Rails.env.production?
113134
CODE
114135

115136
# ----------------------------------- Add NPM modules
116137

117138
run 'yarn add react@16'
118139
run 'yarn add react-dom@16'
119140
run 'yarn add react-router@^5.0.0'
120-
if WITH_PRERENDERING
121141
run 'yarn add react-router-dom@^5.0.0'
122142
# run 'yarn add history' # this will be brought in by react-router
123143
run 'yarn add react_ujs@^2.5.0'
124144
run 'yarn add jquery@^3.4.1'
125-
end
126-
127-
if !WITH_PRERENDERING
128-
# ----------------------------------- Create hyperstack.js
129-
130-
file 'app/javascript/packs/hyperstack.js', <<-CODE
131-
// Import all the modules
132-
import React from 'react';
133-
import ReactDOM from 'react-dom';
134-
135-
// for opal/hyperstack modules to find React and others they must explicitly be saved
136-
// to the global space, otherwise webpack will encapsulate them locally here
137-
global.React = React;
138-
global.ReactDOM = ReactDOM;
139-
CODE
140-
141-
# ----------------------------------- View template
142-
143-
inject_into_file 'app/views/layouts/application.html.erb', before: %r{<%= javascript_include_tag 'application', 'data-turbolinks-track': 'reload' %>} do
144-
<<-CODE
145-
<%= javascript_pack_tag 'hyperstack' %>
146-
CODE
147-
end
148145

149146
# ----------------------------------- application.js
150147

151-
inject_into_file 'app/assets/javascripts/application.js', before: %r{//= require_tree .} do
148+
inject_into_file 'app/assets/javascripts/application.js', before: %r{//= require_tree .} do
152149
<<-CODE
153150
//= require jquery
154151
//= require jquery_ujs
155152
//= require hyperstack-loader
156153
CODE
157-
end
158-
else
159-
# ----------------------------------- Create client_and_server.js
160-
161-
file 'app/javascript/packs/client_and_server.js', <<-CODE
162-
//app/javascript/packs/client_and_server.js
163-
// these packages will be loaded both during prerendering and on the client
164-
React = require('react'); // react-js library
165-
History = require('history'); // react-router history library
166-
ReactRouter = require('react-router'); // react-router js library
167-
ReactRouterDOM = require('react-router-dom'); // react-router DOM interface
168-
ReactRailsUJS = require('react_ujs'); // interface to react-rails
169-
// to add additional NPM packages call run add yarn package-name@version
170-
// then add the require here.
171-
CODE
172-
173-
# ----------------------------------- Create client_only.js
174-
175-
file 'app/javascript/packs/client_only.js', <<-CODE
176-
//app/javascript/packs/client_only.js
177-
// add any requires for packages that will run client side only
178-
ReactDOM = require('react-dom'); // react-js client side code
179-
jQuery = require('jquery');
180-
// to add additional NPM packages call run add yarn package-name@version
181-
// then add the require here.
182-
CODE
183-
184-
# ----------------------------------- add asset paths
185-
186-
# note before this was just public/packs now its public/paths/js. WHY???
187-
append_file 'config/initializers/assets.rb' do
188-
<<-RUBY
189-
Rails.application.config.assets.paths << Rails.root.join('public', 'packs', 'js').to_s
190-
RUBY
191-
end
192-
inject_into_file 'config/environments/test.rb', before: /^end/ do
193-
<<-RUBY
194-
195-
# added by hyperstack installer
196-
config.assets.paths << Rails.root.join('public', 'packs-test', 'js').to_s
197-
RUBY
154+
end
198155

156+
# ----------------------------------- Uglifier for ES6
199157

200-
# ----------------------------------- application.js
201-
202-
inject_into_file 'app/assets/javascripts/application.js', before: %r{//= require_tree .} do
203-
<<-CODE
204-
//= require hyperstack-loader
205-
CODE
206-
end
207-
end
158+
gsub_file 'config/environments/production.rb', /(?:\:uglifier)\n/, "Uglifier.new(harmony: true)\n"
208159

209160
# ----------------------------------- Procfile
210161

@@ -236,8 +187,11 @@ class App < HyperComponent
236187
# Route('/user/:id/name', mounts: UserName) : path segments beginning with a colon will be captured in the match param
237188
# see the hyper-router gem documentation for more details
238189
239-
render do
190+
render(DIV) do
240191
H1 { "Hello world from Hyperstack!" }
192+
BUTTON {"Click me"}.on(:click) do
193+
alert("All working!")
194+
end
241195
end
242196
end
243197
CODE
@@ -247,10 +201,12 @@ class App < HyperComponent
247201
# must be inserted AFTER route get ... so it ends up before in the route file!
248202
route "mount Hyperstack::Engine => '/hyperstack'"
249203

250-
# ----------------------------------- Commit Hyperstack setup
204+
205+
# ----------------------------------- Commit Hyperstack setup and create db
251206

252207
after_bundle do
253208
run 'bundle exec rails webpacker:install'
254209
git add: "."
255210
git commit: "-m 'Hyperstack config complete'"
211+
run 'rake db:create'
256212
end

‎install/readme.md‎

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,15 @@ And for a full system that includes Webpack for managing javascript assets you w
1111
#### - Yarn ([Install Instructions](https://yarnpkg.com/en/docs/install))
1212
#### - NodeJS: ([Install Instructions](https://nodejs.org))
1313

14+
## Createing a new app with a Rails template
1415

15-
## Creating a Test Rails App
16+
This template will create a new app with Webpacker, Hyperstack and Postgres and will deploy to Heroku
17+
18+
```shell
19+
rails new MyApp --database=postgresql --template=https://rawgit.com/hyperstack-org/hyperstack/edge/install/rails-webpacker.rb
20+
```
21+
22+
## Creating a Test Rails App (without using the template)
1623

1724
You can install Hyperstack in existing Rails apps, or you can create a new Rails app using the Rails `new` command. For example to create a new app called `MyApp` you would run
1825

@@ -365,11 +372,12 @@ These two files look like this and are placed in the `app/javascript/packs` dire
365372
```javascript
366373
//app/javascript/packs/client_and_server.js
367374
// these packages will be loaded both during prerendering and on the client
368-
React = require('react'); // react-js library
369-
History = require('history'); // react-router history library
370-
ReactRouter = require('react-router'); // react-router js library
371-
ReactRouterDOM = require('react-router-dom'); // react-router DOM interface
372-
ReactRailsUJS = require('react_ujs'); // interface to react-rails
375+
React = require('react'); // react-js library
376+
createReactClass = require('create-react-class'); // backwards compatibility with ECMA5
377+
History = require('history'); // react-router history library
378+
ReactRouter = require('react-router'); // react-router js library
379+
ReactRouterDOM = require('react-router-dom'); // react-router DOM interface
380+
ReactRailsUJS = require('react_ujs'); // interface to react-rails
373381
// to add additional NPM packages call run yarn add package-name@version
374382
// then add the require here.
375383
```
@@ -406,15 +414,16 @@ end
406414

407415
#### Manage the Hyperstack dependencies with yarn
408416

409-
As you can see above the NPM modules that Hyperstack depends on are part of the webpacker manifests.
410-
But by default Hyperstack will pull copies of these packages into the old-school Rails sprockets asset pipeline.
411-
So if you are using Webpacker you need to add the packages using yarn, and then tell Hyperstack not to
412-
include them in the sprockets asset pipeline.
417+
The above changes will pull the necessary NPM modules in as part of the webpacker manifests.
418+
But by default Hyperstack will try to pull copies of these packages from the Hyperstack gem set using the old-school Rails sprockets asset pipeline.
419+
420+
So instead, when using webpacker, you need to add the packages using the `yarn` package manager, and then tell Hyperstack not to include them in the sprockets asset pipeline.
413421

414422
To add the packages using yarn run these commands:
415423

416424
```bash
417425
yarn add react@16
426+
yarn add create-react-class
418427
yarn add react-dom@16
419428
yarn add react-router@^5.0.0
420429
yarn add react-router-dom@^5.0.0

0 commit comments

Comments
 (0)