|
| 1 | +# Contribute |
| 2 | + |
| 3 | +Please make sure to read the general notes about contribution [here](https://docs.matestack.io/about/community-team/contribute) |
| 4 | + |
| 5 | +In order to work on the code to add features or fix reported bugs, you should clone the repo first: |
| 6 | + |
| 7 | +```bash |
| 8 | +git clone [email protected]:matestack/matestack-ui-vuejs.git |
| 9 | +cd matestack-ui-vuejs |
| 10 | +git checkout -b "your_feature/bugfix_branch_name" |
| 11 | +``` |
| 12 | + |
| 13 | +We dockerized the core development/testing in order to make it as convenient as possible to contribute to `matestack-ui-vuejs`. |
| 14 | + |
| 15 | +You will need to install docker and docker-compose: |
| 16 | + |
| 17 | +* [Install Docker on Ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/#install-using-the-convenience-script) |
| 18 | +* [Install docker-compose](https://docs.docker.com/compose/install/) |
| 19 | + |
| 20 | +## Dummy app |
| 21 | + |
| 22 | +**Setup the dummy app** |
| 23 | + |
| 24 | +In order to migrate the database and install yarn/npm packages, do: |
| 25 | + |
| 26 | +``` |
| 27 | +docker-compose build dummy |
| 28 | +docker-compose run --rm dummy yarn install |
| 29 | +docker-compose run --rm dummy sh -c "cd spec/dummy && npm install" |
| 30 | +docker-compose run --rm dummy bundle exec rake db:setup SKIP_TEST_DATABASE=true |
| 31 | +``` |
| 32 | + |
| 33 | +{% hint style="danger" %} |
| 34 | +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. |
| 35 | +{% endhint %} |
| 36 | + |
| 37 | +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 |
| 38 | + |
| 39 | +{% hint style="info" %} |
| 40 | +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. |
| 41 | +{% endhint %} |
| 42 | + |
| 43 | +{% hint style="warning" %} |
| 44 | +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. |
| 45 | + |
| 46 | +That does not apply for **JavaScript** files as they are compiled via Webpacker automatically without a server restart required. |
| 47 | +{% endhint %} |
| 48 | + |
| 49 | +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. |
| 50 | + |
| 51 | +The pages/component used in the dummy app live in `spec/dummy/app/matestack`. |
| 52 | + |
| 53 | +#### Run the Webpack watcher |
| 54 | + |
| 55 | +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: |
| 56 | + |
| 57 | +``` |
| 58 | +docker-compose up webpack-watcher |
| 59 | +``` |
| 60 | + |
| 61 | +#### Rerun bundle/yarn install in a Docker container |
| 62 | + |
| 63 | +In order to execute commands such as `bundle install`, `yarn install` or `npm install` you need to run: |
| 64 | + |
| 65 | +``` |
| 66 | +docker-compose run --rm dummy bundle install |
| 67 | +docker-compose run --rm dummy yarn install |
| 68 | +docker-compose run --rm dummy sh -c "cd spec/dummy && npm install" |
| 69 | +``` |
| 70 | + |
| 71 | +#### Optional: run commands as your user in a Docker container |
| 72 | + |
| 73 | +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. |
| 74 | + |
| 75 | +``` |
| 76 | +CURRENT_UID=$(id -u):$(id -g) docker-compose run --rm dummy bash |
| 77 | +
|
| 78 | +# and then your desired command such as: |
| 79 | +
|
| 80 | +rails generate ... |
| 81 | +``` |
| 82 | + |
| 83 | +Otherwise the generated files will be owned by the `root` user and are only writeable when applying `sudo`. |
| 84 | + |
| 85 | +**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. |
| 86 | + |
| 87 | +## Testing |
| 88 | + |
| 89 | +To assure this project is and remains in great condition, we heavily rely on automated tests. Tests are defined in `/spec` folder |
| 90 | + |
| 91 | +**Setup the test ENV** |
| 92 | + |
| 93 | +``` |
| 94 | +docker-compose build test |
| 95 | +docker-compose run --rm test yarn install |
| 96 | +docker-compose run --rm test sh -c "cd spec/dummy && npm install" |
| 97 | +docker-compose run --rm test bundle exec rake db:setup |
| 98 | +``` |
| 99 | + |
| 100 | +{% hint style="danger" %} |
| 101 | +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. |
| 102 | +{% endhint %} |
| 103 | + |
| 104 | +{% hint style="info" %} |
| 105 | +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. |
| 106 | +{% endhint %} |
| 107 | + |
| 108 | +**Run the specs** |
| 109 | + |
| 110 | +```bash |
| 111 | +docker-compose run --rm --service-ports test bash |
| 112 | + |
| 113 | +# and then inside the container: |
| 114 | + |
| 115 | +cd spec/dummy |
| 116 | +./bin/webpack # always make sure to have the latest JS assets compiled |
| 117 | + |
| 118 | +cd ../.. |
| 119 | + |
| 120 | +bundle exec rspec spec/test # run all tests |
| 121 | +bundle exec rspec spec/test/components/xyz.rb(:123) # run a specific test (:line_number) |
| 122 | +``` |
| 123 | + |
| 124 | +{% hint style="info" %} |
| 125 | +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. |
| 126 | +{% endhint %} |
| 127 | + |
| 128 | +## Documentation & test coverage |
| 129 | + |
| 130 | +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! |
| 131 | + |
| 132 | +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! |
| 133 | + |
| 134 | +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. |
0 commit comments