Skip to content

Commit 6ca9435

Browse files
jonasjabarigitbook-bot
jonasjabari
authored and
gitbook-bot
committed
GitBook: [main] one page modified
1 parent 58e8189 commit 6ca9435

File tree

1 file changed

+80
-89
lines changed

1 file changed

+80
-89
lines changed

‎docs/community/contribute.md

Lines changed: 80 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -1,168 +1,159 @@
11
# Contribute \[WIP\]
22

3-
We are very happy about anyone that wants to improve this project! Please make sure to read this guide before starting your work to avoid unnecessary trouble down the road! Always feel welcomed to reach out to us via [Discord](https://discord.gg/c6tQxFG) or mail if you are unsure or need further information.
3+
We are very happy about anyone that wants to improve this project! Please make sure to read this guide before starting your work to avoid unnecessary trouble down the road!
44

5-
## What to work on
5+
{% hint style="info" %}
6+
Always make sure to reach out to us via [Discord](https://discord.gg/c6tQxFG) or mail \([email protected]\) if you want to start developing features or fixing bugs! It's way easier for you to get going if you get some initial support from the Core Team :\)
7+
{% endhint %}
68

7-
If you want to contribute and are unsure what to work on, take a look at the [open issues!](https://github.com/matestack/matestack-ui-core/issues)
9+
Asking questions, creating GitHub Issues, adjusting things through PRs... every kind of community contribution counts:
810

9-
Other case: You plan to built something that you think should be part of the Matestack UI Core \(or you have already built it\)? Great, then open a pull request and we will take a look!
11+
## Reporting issues
1012

11-
## How to contribute
13+
\[WIP\]
1214

13-
Please create a pull request to the `develop` branch with your tested and documented code. Bonus points for using our PR template!
15+
## Propose features
1416

15-
## Documentation
17+
\[WIP\]
1618

17-
Documentation can be found in the `/docs/*` folder. Please make sure to cover basic use cases of your concepts & components for other users! Feel free to take a look at other examples and copy their structure!
19+
## Adding features or fixing bugs
1820

19-
Note: We will not approve pull requests that introduce new concepts or components without documentation. Same goes for existing concepts & components. If you change the behavior of an existing part of this project, make sure to also update the corresponding part of the documentation!
21+
In order to work on the core code to add features or fix reported bugs, you should clone the repo first:
2022

21-
## Dockerized Core Dev
23+
```bash
24+
git clone [email protected]:matestack/matestack-ui-core.git
25+
cd matestack-ui-core
26+
git checkout -b "your_feature/bugfix_branch_name"
27+
```
2228

23-
We dockerized the core development in order to make it as convenient as possible to contribute to `matestack-ui-core`.
29+
We dockerized the core development/testing in order to make it as convenient as possible to contribute to `matestack-ui-core`.
2430

2531
You will need to install docker and docker-compose:
2632

2733
* [Install Docker on Ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/#install-using-the-convenience-script)
2834
* [Install docker-compose](https://docs.docker.com/compose/install/)
2935

30-
### Setup Database and Yarn Packages
36+
### Dummy app
37+
38+
#### Setup the dummy app
3139

32-
In order to migrate the database and install yarn packages, do:
40+
In order to migrate the database and install yarn/npm packages, do:
3341

3442
```text
35-
docker-compose run --rm dummy bundle exec rake db:setup
43+
docker-compose build dummy
3644
docker-compose run --rm dummy yarn install
37-
docker-compose run --rm dummy sh -c "cd builder && yarn install"
38-
docker-compose run --rm dummy sh -c "cd spec/dummy && yarn install"
45+
docker-compose run --rm dummy sh -c "cd spec/dummy && npm install"
46+
docker-compose run --rm dummy bundle exec rake db:setup SKIP_TEST_DATABASE=true
3947
```
4048

41-
If you already created sqlite files locally in `spec/dummy/db`, the command `docker-compose run --rm dummy bundle exec rake db:migrate` will fail. Please remove the locally created sqlite files and rerun `docker-compose run --rm dummy bundle exec rake db:migrate`
49+
{% hint style="danger" %}
50+
The JavaScript packages within the dummy folder have to be resolved via NPM unlike the JavaScript packages within the root directory, which are resolved via YARN.
51+
{% endhint %}
4252

43-
You might need to redo these steps if new migrations or yarn packages are added/updated.
53+
If you already created sqlite files locally in `spec/dummy/db`, the command `docker-compose run --rm dummy bundle exec rake db:setup SKIP_TEST_DATABASE=true` will fail. Please remove the locally created sqlite files and rerun the command
4454

45-
### Run the Dummy App
55+
{% hint style="info" %}
56+
You might need to redo these steps if new migrations or yarn/npm packages are added/updated. Always remember to resolve JavaScript packages with NPM within the dummy app rather than using YARN.
57+
{% endhint %}
4658

47-
The dummy app provides a good playground for matestacks core development. The source code can be found and manipulated \(be careful what you commit\) at `spec/dummy`. Run it like seen below:
59+
#### Run the dummy app
60+
61+
The dummy app provides a good playground for Matestacks core development in order to review effects of core implementation changes hands on in a browser. The source code can be found and manipulated \(be careful what you commit\) at `spec/dummy`. Run it like seen below:
4862

4963
```text
5064
docker-compose up dummy
5165
```
5266

53-
Visit `localhost:3000/sandbox/hello` in order to visit the sandbox page. It lives in `spec/dummy/app/matestack/pages/sandbox/hello.rb`. Feel free to modify it and play around with components and concepts. Just don't push your local changes to the remote repo.
67+
{% hint style="warning" %}
68+
Be aware that whenever you change any **Ruby** file within the core implementation, you need to restart the dummy app in order to see effects of your changes within the dummy app. Currently the core code, defined in `lib` is not automatically reloaded. We want to fix that soon.
69+
70+
That does not apply for **JavaScript** files as they are compiled via Webpacker automatically without a server restart required.
71+
{% endhint %}
5472

55-
Visit `localhost:3000/my_app/my_first_page` in order to visit some example use cases. The pages live in `spec/dummy/app/matestack/pages/my_app`.
73+
Visit `localhost:3000` in order to visit the dummy app. Feel free to modify it and play around with components and concepts. Just don't push your local changes to the remote repo.
5674

57-
### Run the Webpack Watcher
75+
The pages/component used in the dummy app live in `spec/dummy/app/matestack`.
5876

59-
The builder app located in `builder/` uses webpacker in order build matestacks Javascript based on the source code found in `app/`. During development it can be used to compile the JavaScript when any relevant source code is changed. Run it like seen below:
77+
### Run the Webpack watcher
78+
79+
During development, the Webpack watcher can be used to compile the JavaScript when any relevant JavaScript source code is changed. Run it in a separate terminal tab like seen below:
6080

6181
```text
6282
docker-compose up webpack-watcher
6383
```
6484

65-
### Run bundle/yarn install in a Docker container
85+
### Rerun bundle/yarn install in a Docker container
6686

67-
In order to execute commands such as `bundle install`, `yarn install` you need to run:
87+
In order to execute commands such as `bundle install`, `yarn install` or `npm install` you need to run:
6888

6989
```text
7090
docker-compose run --rm dummy bundle install
7191
docker-compose run --rm dummy yarn install
72-
docker-compose run --rm dummy sh -c "cd spec/dummy && yarn install"
92+
docker-compose run --rm dummy sh -c "cd spec/dummy && npm install"
7393
```
7494

75-
### Run commands as your user in a Docker container
95+
### Optional: run commands as your user in a Docker container
7696

77-
When running commands, which generates files, which then are mounted to your host filesystem, you need to tell the Docker container that it should run with your user ID.
97+
When running commands, which generates files \(e.g. rails generator usage\), which then are mounted to your host filesystem, you need to tell the Docker container that it should run with your user ID.
7898

7999
```text
80100
CURRENT_UID=$(id -u):$(id -g) docker-compose run --rm dummy bash
81101
82-
#and then your desired command such as:
102+
# and then your desired command such as:
83103
84-
rails generate matestack:core:component div
104+
rails generate ...
85105
```
86106

87107
Otherwise the generated files will be owned by the `root` user and are only writeable when applying `sudo`.
88108

89109
**Note:** `bundle install` and `yarn install` can't be executed inside the Docker container as the current user. `CURRENT_UID=$(id -u):$(id -g) docker-compose run --rm dummy bundle install` will not work.
90110

91-
## Core Components Generator
111+
### Testing
92112

93-
```bash
94-
CURRENT_UID=$(id -u):$(id -g) docker-compose run --rm dummy bash
95-
rails generate matestack:core:component div
96-
```
113+
To assure this project is and remains in great condition, we heavily rely on automated tests. Tests are defined in `/spec` folder
97114

98-
This will create a component for the HTML `<div>` tag and will generate the following files:
115+
#### Setup the test ENV
99116

100-
```bash
101-
app/concepts/matestack/ui/core/div/div.haml
102-
app/concepts/matestack/ui/core/div/div.rb
103-
spec/usage/components/div_spec.rb
104-
docs/components/div.md
117+
```text
118+
docker-compose build test
119+
docker-compose run --rm test yarn install
120+
docker-compose run --rm test sh -c "cd spec/dummy && npm install"
121+
docker-compose run --rm test bundle exec rake db:setup
105122
```
106123

107-
## Dockerized Test Env
108-
109-
```bash
110-
bundle install
111-
yarn install
112-
cd spec/dummy
113-
yarn install # dependencies for the dummy app in testing
114-
cd ../..
115-
116-
bundle exec rake db:create
117-
bundle exec rake db:schema:load
118-
```
124+
{% hint style="danger" %}
125+
The JavaScript packages within the dummy folder have to be resolved via NPM unlike the JavaScript packages within the root directory, which are resolved via YARN.
126+
{% endhint %}
119127

120-
## Tests
128+
{% hint style="info" %}
129+
You might need to redo these steps if new migrations or yarn/npm packages are added/updated. Always remember to resolve JavaScript packages with NPM within the dummy app rather than using YARN.
130+
{% endhint %}
121131

122-
To assure this project is and remains in great condition, we heavily rely on automated tests. Tests are defined in `/spec` folder and can be executed by running:
132+
#### Run the specs
123133

124134
```bash
125-
docker-compose run --rm test bash
126-
bundle exec rake db:setup #once initially
127-
bundle exec rspec spec/usage/components
128-
```
129-
130-
Tests follow quite the same rules as the documentation: Make sure to either add relevant tests \(when introducing new concepts or components\) or change existing ones to fit your changes \(updating existing concepts and components\). Pull requests that add/change concepts & components and do not come with corresponding tests will not be approved.
131-
132-
## Core Components
135+
docker-compose run --rm --service-ports test bash
133136

134-
Core Components are an essential part of the `matestack-ui-core` gem. If you are planning to contribute to Matestack you can start doing that by creating a core component. To help you getting started you can use the Core Component Generator.
137+
# and then inside the container:
135138

136-
The generator will create a matestack core component to `app/concepts/matestack/ui/core`.
137-
138-
Example:
139-
140-
```bash
141-
rails generate matestack:core:component div
142-
```
139+
cd spec/dummy
140+
./bin/webpack # always make sure to have the latest JS assets compiled
143141

144-
This will create a component for the HTML `<div>` tag and will generate the following files:
142+
cd ../..
145143

146-
```bash
147-
app/concepts/matestack/ui/core/div/div.haml
148-
app/concepts/matestack/ui/core/div/div.rb
149-
spec/usage/components/div_spec.rb
150-
docs/components/div.md
144+
bundle exec rspec spec/test # run all tests
145+
bundle exec rspec spec/test/components/xyz.rb(:123) # run a specific test (:line_number)
151146
```
152147

153-
## Release
148+
{% hint style="info" %}
149+
Always make sure to compile the JavaScript assets via `./bin/webpack` in the `spec/dummy` folder before running the specs. You can also run `./bin/webpack --watch` in a separate test container \(without `--service-ports`\). The compiled assets are mounted to your filesystem.
150+
{% endhint %}
154151

155-
[Webpacker](https://github.com/rails/webpacker) is used for managing all JS assets. In order to create production-ready assets, run the [task](https://github.com/matestack/matestack-ui-core/blob/master/Rakefile)
152+
## Documentation & test coverage
156153

157-
```text
158-
docker-compose run --rm webpack-watcher bash
159-
cd builder
160-
bundle exec rails webpacker:compile RAILS_ENV=production
161-
```
162-
163-
The assets will be exported to [`vendor/assets/javascripts/dist`](https://github.com/matestack/matestack-ui-core/tree/master/vendor/assets/javascripts/dist).
154+
Documentation can be found in the `/docs/*` folder. Please make sure to cover basic use cases of your concepts & components for other users! Feel free to take a look at other examples and copy their structure!
164155

165-
Under the hood, we use a "builder" app in the [`builder`](https://github.com/matestack/matestack-ui-core/tree/master/builder) folder in order to run webpacker and create the assets. Its webpack\(er\) configuration can be found in [`builder/config`](https://github.com/matestack/matestack-ui-core/tree/master/builder/config).
156+
Note: We will not approve pull requests that introduce new concepts or components without documentation. Same goes for existing concepts & components. If you change the behavior of an existing part of this project, make sure to also update the corresponding part of the documentation!
166157

167-
When creating a new matestack-ui-core release, make sure to also change the version number accordingly in [`package.json`](https://github.com/matestack/matestack-ui-core/blob/master/package.json) and to create a corresponding [version tag on github](https://github.com/matestack/matestack-ui-core/tags).
158+
Tests follow quite the same rules as the documentation: Make sure to either add relevant tests \(when introducing new concepts or components\) or change existing ones to fit your changes \(updating existing concepts and components\). Pull requests that add/change concepts & components and do not come with corresponding tests will not be approved.
168159

0 commit comments

Comments
 (0)