This guide will detail the process of contributing core and extensions code.

Contributor or Committer?

ARIA is an incubation project under the Apache Software Foundation. The ASF defines the roles of Contributor and Committer on their website. An important difference between a contributor and a committer is that committers have write permissions for the code repository. Contributors are welcome to offer code contributions via forks + pull requests. See more information in the ASF's getting involved, new contributors, and new committers guides.

Becoming a Committer

Once you've contributed code as a contributor, the ARIA PMC may invite you to join the project as a committer. To become a committer and receive write permissions, you'll be required to sign the ICLA agreement. Read more about this agreement in Apache's new committers guide.

What to Contribute

You can look for issues at ARIA's JIRA using a filter for open issues without an assignee. Some issues are marked with a "simple" label - those issues may be a good entry point for a new contributor. You can use this filter to view these issues. If you have an idea for a new feature which doesn't have an open ticket, you're welcome to propose it on ARIA's dev mailing list.

Git Setup

ARIA's git repository is located at https://git-wip-us.apache.org/repos/asf/incubator-ariatosca.git. It is also available on the read-only github mirror at https://github.com/apache/incubator-ariatosca. Committers can simply clone from the Apache git repository, create an ARIA-XXXX branch (XXXX being the JIRA issue number) and push code. Contributors who are not committers should fork from the github repository.

Development Environment Setup

For development purposes, it's recommended to install ARIA in editable mode. After creating a python virtualenv, install ARIA by first running:

make install-virtual

Working on an Issue

All code contributions need to have an identifying JIRA ticket (see ARIA's JIRA guidelines). When starting to work on an issue, please assign it to yourself and mark it as In Progress status in JIRA. (Note: At the moment, you must first be assigned with a "Contributor" role on JIRA before being able to be assigned with issues. To be assigned with this role, please send a request on the dev mailing list).

Commits are linked to JIRA issues automatically by a git-JIRA integration, which requires commit, branch and PR descriptions to begin with a reference to the relevant issue (e.g. "ARIA-123"). See more in the commit message guidelines section. By convention, branch names should be all in small case letters, with words separated by hyphens.

Before beginning to code, please take a moment to familiarize yourself with the code style guidelines as well as the code documentation style guidelines.

While coding, make sure to add any relevant automatic tests as well. It is recommended to run tests locally often, and also to generate and test documentation. It is recommended to rebase your branch on top of master often, to make sure you're working against the most recent changes, and to avoid more complicated merge conflicts later on.

Testing

The prerequisites are that you must have both Python 2.7 and Python 2.6 installed. To run all tests, including code style validation on Python 2.7:

make test

If you want to run individual test suites, you can install tox and specify the environment (see tox.ini for all of them):

pip install tox
tox -e py27

Running Python 2.6 tests might be a bit tricky on newer operating systems. You can install Python 2.6 using pythonbrew:

sudo apt install libsqlite3-dev
pip install pythonbrew
pythonbrew_install
source "$HOME/.pythonbrew/etc/bashrc"
pythonbrew install 2.6.9
pythonbrew symlink

To run: 

PY26=py2.6.9 tox -e py26

It is also possible to run tests and validation using pytest and pylint directly, but keep in mind the CI tools will run using tox, and there may be some discrepancies between runs made by tox and ones made directly by those tools. 

Creating Pull Requests

Code gets introduced into ARIA via pull requests (PRs) on GitHub. Every PR must be reviewed by at least one committer (excluding the author, in the case they're a committer). Please consider writing on the dev@ mailing list in cases where the PR does or will contain many and complicated changes, to give more detailed description of the changes and possibly also to have reviewers start taking a look over code which is still work in progress.

A PR needs to adhere to the following:

1) It is required that the PR passes all CI tests and validations. ARIA currently uses TravisCI and AppVeyor for PR CI (Apache's Jenkins is also used, but it does not run automatically on PRs). Please make sure the PR passes all checks before asking someone to review your code.

2) It should contain a single commit. Make sure to squash your commits if you have more than a single one.
Note that during the review process, it's sometimes easier to review only incremental changes, at which time it's ok not to squash the commits - however, once the review is complete, and prior to merging the code, squashing to a single commit should be done.
Keep in mind that when adding additional commits to an existing PR, the PR's description doesn't change automatically (even if the commit message's been modified), so it should be adjusted as well. 

3) It should contain tests and documentation relevant to the changes made.

Reviewing Code

When reviewing a PR, make sure first that the PR adheres to the three rules mentioned in the previous section.
Other criterias which is recommended to be taken into account when reviewing includes:

  • The code follows code guidelines and maintains code consistency
  • Simplicity / complexity of the added code
  • API changes / breaks / addition (the latter affecting future changes, as it'll be required to support the new APIs)
  • Amount of code added / risk of introducing the new code to the main branch
  • Mailing list discussions relevant to the specific PR (e.g. any agreements / disagreements that might have arose)

Merging Code

Since the Github repository is read-only, merging the code requires committers to work with the Apache repository.

To merge a committer's PR (merging from a branch), the recommended flow for merging is:

1) git checkout ARIA-XXXX
2) git pull origin ARIA-XXXX
3) git checkout master
4) git pull origin master
5) git rebase ARIA-XXXX

If the branch were properly rebased on top of master, step (5) should result in a simple fast-forward, and introduce no conflicts.
The final step would be to push the changes:

6) git push origin master

Under no circumstances should you use the -f flag in (6) - If a conflict was found, it means the branch should be rebased on top of master again before it's merged. Abort your rebase using git rebase --abort, and ask the committer to properly set up their branch for merge.

Finally, don't forget to delete the committer's remote branch (so to avoid clutter of many stale branches):

7) git push origin --delete ARIA-XXXX 

To merge a contributor's PR (merging from a fork), the recommended flow for merging is:

1) git checkout master
2) git pull origin master
3) git pull --squash <URL-OF-REPO> <BRANCH-NAME>

If the fork were properly rebased on top of master, step (3) should introduce no conflicts.
Unlike the case with rebase, the code will be in the git index rather than committed if a squash took place (otherwise, simply skip to step (5)), and so the next step is to commit it:

4) git commit
The commit message will default to a message encapsulating the original commit message(s). Edit it so only the original commit message remains.
Note that in the case where this step is required, the author of the commit will become you. This can be modified using the --author flag, like so: git commit --author="Author Name <email@address.com>"

Finally, push the commit:

5) git push origin master 

Note that the recommended flows for merging branches and forks differ, but only the sake of ease of use. It is also possible to use alternatives:

a) When merging a branch, one can replace step (5) with git merge --squash (which is similar to git pull --squash in the recommended fork merging flow). The downside is the need to modify the commit message manually.
b) When merging a fork, one could first add the remote repository, fetch the relevant branch, and rebase from that remote branch (which is similar to the recommended branch merging flow). The downside is the need to add and later remove the remote repository.

Note that whether the PR was for a branched or forked commit, both these flows should result in the Github PR changing its status to "Merged" automatically.

  • No labels