Contributing to azk
First off, you're awesome! Thanks for taking the time to contribute to
There's a bunch of ways to help, and we welcome any and all of them:
- Opening issues
- Commenting on open issues
- Sending PRs
- Testing PRs
- Writing tests
- Writing documentation
- Fixing typos
Below you can find a few sections with more detailed information. We also recommend taking a look at GitHub's own guide "Contributing to Open Source on GitHub".
- Questions and support
- Reporting issues
- Tips and guidelines
- Pull Requests
Questions and support
The documentation for
azk, the one you are reading right now, is the main source of information about the project. We also have a chat on Gitter in English and Portuguese that can be useful to ask questions in real time, directly to our team of developers or other members of the community.
Before creating new issues please make sure there are no similar ones already created. If you do find one similar, add a :+1: comment to it, and also any information that might be different from the person who first opened the issue, for example: OS,
azk version, etc.
Ideally, an issue should contain a basic description of your system, a description of the error, and instructions on how to reproduce it. We encourage you to open an issue even if you cannot remember the steps to trigger it again in case it's intermittent.
An example of a good format for an issue:
Description of the problem: `OS`: `azk version`: Environment details (VirtualBox, DigitalOcean, etc.): Steps to Reproduce: 1. 2. 3. Actual Results: Expected Results: Additional info:
Tips and guidelines
/bin: azk executables:
azkdocumentation in Gitbook format.
azkmain Azkfile.js. Sets the dns and the balancer.
locales/en-US.js: All messages and texts displayed by the
azkcli are here.
templates/Azkfile.mustache.js: Template of an Azkfile.js written in mustache (Handlebars-flavored).
/src: Source code.
/lib: Compiled source code.
.dependencies: File in which dependencies versions are defined.
.jscsrc: Sets the code style pattern.
Makefile: Tasks for packaging.
npm-shrinkwrap.json: Locked version of
gulpfile.js: Gulp tasks. For more info, run
azk nvm gulp help.
azk's code is written in Node.js. It uses several features of ES6 that are not yet available in a stable version, so the code goes through a compilation step for it to be correctly interpreted by the current version of Node. We use babeljs for that, which provides many features from ES6 (see: babeljs compat-table). During the transpilation process, we always set the
source-map to on. This allows the generated code to show errors that correctly point to the original source code.
One thing that you'll note as soon as you start diving in
azk's code is the use of
generators. This allows our asynchronous code to become more similar to synchronous code, making it easier to read. We use the promises library bluebird-generators that supports generators.
Code quality and style
.jscsrc configured with
esnext enabled, i.e. with various features of ES6. Check the links below for the best way to set up your editor to integrate these code quality verification tools:
We also use a
.editorconfig file to help maintain a consistent coding style no matter which editor or IDE you're using. You can learn more about EditorConfig files here, and check how ours is setup here.
Task tool - Gulp
azk's development, we use gulp to coordinate the tasks of day-to-day development, such as:
- Checking code quality with
- Running a "watch" command for file modification and performing the tasks above automatically;
You can find the full list of tasks available by running:
azk nvm gulp help, but the main task you should be aware of and using during development is
azk nvm gulp watch:test:lint.
First of all, grab
azk from source and build its binary:
$ git clone https://github.com/azukiapp/azk.git $ cd azk $ make
Then add the path to your azk binary to your PATH environment variable, or create an alias to it.
There's additional steps that you need to go through if you're installing it on a Mac or a Linux (for example, installing the
libnss-resolver). Check this page for more detailed instructions.
As mentioned in the "Implementation Details" section,
azk is written in Node.js, and it uses several features of ES6. One thing to note is that, for developing and contributing to
azk, you don't need to have Node.js installed in your machine.
azk has a version of Node.js, which is the same we use to test it and develop it, inside the folder "
./lib/nvm". It comes already installed and pre-packaged when you grab
azk from a package manager, or it's installed if you grab it from GitHub and run
make to build a binary. That means that we can:
- Make sure that
azkis being executed and using a Node.js version that we tested.
- Not require the user to have Node.js installed in its machine, and if they do, not affect their development environment in any way.
During development, in case you want to use node commands, you can run:
$ azk nvm node [command] # Or $ azk nvm npm [command]
If you want to install any dependencies, it might work similar to this:
$ azk nvm npm install gulp
And then you can use it by running:
$ azk nvm gulp
We always welcome code contributions, be it fixing an issue or adding new features.
The general workflow follows these steps:
- Open an issue / Find an issue / Suggest a feature via our GitHub Issues page
- Discuss the issue/feature with our team of developers and community members
- Take ownership of the issue/feature
- Create a feature branch and begin work
- Sync your work with the main branch from time to time
- Open PR and iterate
- Accepted and Merged!
In shell commands, that will look something like:
# Fork azk repository $ git clone https://github.com/your_username/azk.git $ cd azk $ git checkout -b feature/feature_name # Make changes to files $ make # Run tests $ azk nvm npm test $ git add . $ git commit -m "[my new feature] Fixing some system tests" $ git push # Open PR from your feature branch to azk's master branch
Remember to make a fork directly on GitHub. All contributions are made through Pull Requests to the main repository
masteris the development branch.
masterbranch is where new features are started, and where they are merged.
stableis the stable version.
stablebranch is the latest stable version of
azk. It's the one which we use to build the binaries, available on package managers.
When creating a branch that you're going to work on, remember to name it as
The commit message follows the convention:
git commit -m '[YOUR_BRANCH_NAME] comment'
This helps us when querying and filtering the git history, to see where changes came from in the future.
To run the
azk tests, the
azk agent must be running:
$ azk agent start ... azk: Agent has been successfully started. $ azk nvm npm test
azk integration tests are written using bats and can be found inside the folder "
specs/integration". Before running the tests you need to install some dependencies:
$ make dependencies
Now you can run the integration tests with:
$ azk nvm gulp integration
Note that running these tests requires you to have the
azk agent running.
We can filter the tests to run specific sections, or a single one with:
$ azk nvm gulp test --grep="Azk command init run"
Similar to the functional tests, you can filter which integration tests will be executed:
$ azk nvm gulp integration --grep="force to replace a"
Adding or updating dependencies
To help manage
azk dependencies, we use
npm's shrinkwrap to lock down the versions we use (more information about that here). Because of that, if you need to add a dependency to
azk, or update an existing one, make sure to generate the
npm-shrinkwrap.json file again.
You can find more information about the commands here, but it should be as simples as:
- Run "npm install" in the package root to install the current versions of all dependencies.
- Add or update dependencies. "npm install" each new or updated package individually and then update package.json. Note that they must be explicitly named in order to be installed: running npm install with no arguments will merely reproduce the existing shrinkwrap.
- Validate that the package works as expected with the new dependencies.
- Run "npm shrinkwrap", commit the new npm-shrinkwrap.json, and publish your package.
Opening a Pull Request
Before opening a pull request, make sure that you:
- Test the azk binary with your changes:
$ make # Make sure you're running azk from your development folder, not from a package manager $ azk nvm npm test
- Merge cleanly with master
Your work should merge cleanly with master. In case there was additional work done in master after you created your branch, do a
$ git remote add upstream https://github.com/azukiapp/azk.git $ git fetch --all $ git checkout master $ git merge upstream/master $ git checkout feature/your_feature_name $ git rebase master
In case you have already made a push to your repository, after doing a
rebase you'll need to make a
git push -f.
- Have commits that are small logical units of work
During development you may end up with a big number of commits that may have unclear commit messages, or that could have been squashed together with previous work. One thing you can do is use
git rebase -i to change your previous commits. These changes can range from simply making sure that all commit messages follow the repository conventions, to squashing changes from multiple commits into a single one.
$ git rebase -i HEAD~X # X being the number of commits you want to rebase
If you need help doing any of the above, just open a PR and we'll help you through it. :)
Pull Request format
When opening a pull request, you should include the following information:
Issues that are closed by this PR (Use they keyword "closes", so the issues are closed automatically after the work is merged) Description of the pull request: How to test the PR: 1. 2. 3. Additional info: