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!
Asking questions, creating GitHub Issues, adjusting things through PRs... every kind of community contribution counts:
In order to work on the core code to add features or fix reported bugs, you should clone the repo first:
git clone [email protected]:matestack/matestack-ui-core.gitcd matestack-ui-coregit checkout -b "your_feature/bugfix_branch_name"
We dockerized the core development/testing in order to make it as convenient as possible to contribute to
You will need to install docker and docker-compose:
In order to migrate the database and install yarn/npm packages, do:
docker-compose build dummydocker-compose run --rm dummy yarn installdocker-compose run --rm dummy sh -c "cd spec/dummy && npm install"docker-compose run --rm dummy bundle exec rake db:setup SKIP_TEST_DATABASE=true
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
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:
docker-compose up dummy
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.
The pages/component used in the dummy app live in
docker-compose up webpack-watcher
In order to execute commands such as
yarn install or
npm install you need to run:
docker-compose run --rm dummy bundle installdocker-compose run --rm dummy yarn installdocker-compose run --rm dummy sh -c "cd spec/dummy && npm install"
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.
CURRENT_UID=$(id -u):$(id -g) docker-compose run --rm dummy bash# and then your desired command such as:rails generate ...
Otherwise the generated files will be owned by the
root user and are only writeable when applying
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.
To assure this project is and remains in great condition, we heavily rely on automated tests. Tests are defined in
docker-compose build testdocker-compose run --rm test yarn installdocker-compose run --rm test sh -c "cd spec/dummy && npm install"docker-compose run --rm test bundle exec rake db:setup
docker-compose run --rm --service-ports test bash# and then inside the container:cd spec/dummy./bin/webpack # always make sure to have the latest JS assets compiledcd ../..bundle exec rspec spec/test # run all testsbundle exec rspec spec/test/components/xyz.rb(:123) # run a specific test (:line_number)
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!
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!
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.