Hello 👋!
Maleo.js is an un-opinionated framework to enable Universal Rendering in JavaScript using React with no hassle.
We are here to solve the time consuming setups Universal Rendering Required.
Feel free to contribute to this project. We are grateful for your contributions and we are excited to welcome you abroad!
Happy contributing 🎉!
Clone Repo to Local Machine
Fork this repository to your GitHub account and then clone it to your local machine from forked repo.
$ git clone https://github.com/<username>/maleo.js.git
$ cd maleo.jsAdd Maleo.js repo as upstream to keep your fork up to date
$ git remote add upstream https://github.com/airyrooms/maleo.jsMake sure you are currently on branch canary, if not you can run this command
$ git checkout canary
$ git pull upstream canary # sync with Maleo.js repoSetup
Make sure you are using the same or higher version of Node.js from .nvmrc file. (more info about nvm)
We are using Yarn as package manager
Install yarn as global dependency
$ npm install --global yarnShould the install fails, use sudo
And then, install all the dependencies required by Maleo.js
$ yarnAfter the installation finished, run fix:bin command to fix binary symlink issue
$ yarn fix:binBefore making any changes, please check our issues list, for issues that you want to solve.
Create a new branch based on what kind of contribution you are going to do.
Here is the draft:
| Contributing Type | Branch Prefix | Description |
| Fix | fix/< name > | Fixing current bug or issues |
| Feature | feature/< name > | Adding new feature |
| Optimization | optimization/< name > | Optimize current unoptimized code |
| Documentation | docs/< name > | Add or edit documentation related file |
| Translation | translate/< name > | Add or edit documentation's translation |
| Example | example/< name > | Add or edit Maleo's examples |
For example if you want to contribute to fix bug in Maleo.js you need to create new branch with fix/ as the prefix.
For example:
$ git checkout -b fix/webpack-bugDevelopment
You are now ready to contribute to Maleo.js. Yaay 🤓!
To build the module you can run this command:
$ yarn buildDuring development we are more likely watch our code changes, therefore we use this command:
$ yarn watchThe command above watches for every changes from folder /packages
Test
For every new feature you are required to add unit test.
You can add the unit test on folder test with filename having [feature-name].test.js prefix.
Running test:
$ yarn testYou can also play around with the changes you made on example/playground.
By doing yarn link maleo to the playground you only need to do this once, or everytime after you do yarn install.
To do so you need to go to packages/Maleo.js then run
$ yarn linkYou should see something like
success Registered "@airy/maleo".
After that you go to example/playground and remove @airy/maleo from package.json dependencies, then run yarn to install all dependencies except @airy/maleo.
this need to be done to prevent CommonJS dependencies error: because of duplicate dependencies webpack encounter, due to our monorepo design. If you find this to be cumbersome you can create new project outside Maleo's repo and do the yarn link there instead
After yarn has finished installed all the dependencies, now you can run
$ yarn link @airy/maleoAnd you are good to test your changes on Maleo you have made.
For every changes you have made on Maleo, you need to restart the playground app.
Commit and Push Changes
Awesome 🎉!
You have arrived at this stage, you are almost ready to make your changes available for other people.
After you have made changes and tested, please don't commit the changes using $ git commit, instead use this command:
$ yarn commitThe command above will display a wizard for you to fill, it uses our standard commit message. After you have finished filling the answers, we will run linting and prettify process to your code and stage those changes to the commit to make sure your code have the same formatting as the other.
If you have passed all the process above you can now push your changes! 😙
$ git pushMaking Pull Request
YEAH!! 🎉🎉 You are ready to make your changes available for other people
Your code are now available in your repository, but it's time to make a Pull Request to Maleo.js
Publishing stable version is only reserved for repo admin: @alvinkl, @AndariasSilvanus. For more info please join our discord channel
Make a pull request from Canary to Master and review all the changes stated on the commit messages. If everything looks OK you can now merge the PR using Merge Create a Merge Commit with Commit Message as such.
Ready to Publish Stable [skip ci]
This is required in order to make Master branch keep in sync with Canary branch, because Squash merging will make the history disappear and open up to other push force issue, Rebase also does the same, also we don't want travis-ci to run it's Sync Master to Canary Pipeline.
After done so checkout to the master branch by using this command
$ git fetch upstream master:master
$ git checkout master
$ git log #to check if the log the same with remote's
$ git push origin master --force #to make sure your remote master is the sameNow in order to publish the stable version, start by running this command
$ yarn publish:version-stableThe command above runs lerna version to let lerna show the package that need to bump it's version for the changes it has.
Please review first the semantic versioning, as this will affect all the user that is using this framework
After everything looks good, you should see lerna doing it's magic bumping the version and make changes on the respective package's package.json, do the commit, and do the tagging.
DO WITH PRECAUTIONS
If you happen to find lerna error during tagging, you can delete the tag on your remote, how to delete all git tags on your local and remote, do git reset of the commit to have the same latest commit with remote's master, then redo the publishing again.
After Lerna has done it's job, you should see a new commit with message chore(release): publish stable ... and also the new git tag with the new version such as @airy/[email protected].
Then you can publish this changes to NPM by running this command
$ bash ./ci/publish-stable.shThe command above will run
yarn publish:prepublishthis command is to make sure packages are ready for publishing, usually runs package build specific for publishing.yarn publish:stablethis command runs lerna publish and publish it to NPM, this command will add git head revision to the bottom of respective package'spackage.json
Now you need to ignore the git revision head, since if we commit amend the git revision head, it will remove the tag.
$ git checkout -- .After pushing all the changes above, we need to sync the master branch with canary branch.
By running
$ bash ./ci/travis-sync-master-canary.sh #checkout to canary and push changes to remote canary
$ git push upstream canary #push to upstream remote canaryShould you find any merge conflicts, please resolve it carefully and respectfully. And commit the merge resolution with this message 'chore: syncing master to canary'
During this process, the pipeline will also publish a new canary version for it and during this process you must not merge any PR to make sure the canary.0 version is clean.
How to test Maleo.js on local development machine in the example directory?
Maleo.js is utilizing Lerna and Yarn Workspace to manage the mono repo structure.
So you can use the Maleo.js inside package folder or example folder. Because Yarn Workspace and Lerna has hoisted all the dependencies into root directory. Therefore every app inside example able to add symlinked Maleo.js as dependency.
How to test Maleo.js on your own app during development?
You can run this command insidepackages/Maleo.js directory
$ yarn link # if you are using yarn on your app $ npm link # if you are using npm on your appAnd then go to your app directory and add
@airy/maleo.js to your own app's package.json and run this command:
$ yarn link @airy/maleo.jsAnd you are good to go! Maleo.js are now living in your
node_modules directory as a symlinked module
more: