[Avocado-devel] Collaboration Workflow

[Amador Pahim]

Hello,

We are receiving a good number of Pull Requests from new contributors 
and this is great.

In order to optimize the time spent on code reviews and also the time 
the code writers are investing in adjust the code according to the 
reviews, I'd like to expose my own workflow that I believe is close to 
the workflow used by the others full-time avocado developers.

The hope is that the new comers get inspired by this and probably take 
advantage of it.

As the biggest number of PRs are coming to avocado-misc-tests, I will 
use this repository as example.

- Fork the repository.

- Clone from your fork:

  $ git clone git at github.com:<username>/avocado-misc-tests.git

- Enter directory:

  $ cd avocado-misc-tests/

- Setup upstream:

  $ git remote add upstream 
git at github.com:avocado-framework/avocado-misc-tests.git

At this point, you should have your name and e-mail configured on git. 
Also, we encourage you to sign your commits using GPG signature:

http://avocado-framework.readthedocs.io/en/latest/ContributionGuide.html#signing-commits

Start coding:

- Create a new local branch and checkout to it:

  $ git checkout -b my_new_local_branch

- Code and then commit your changes:

  $ git add new-file.py
  $ git commit -s (include also a '-S' if signing with GPG)

Please write a good commit message, pointing motivation, issues that 
you're addressing. Usually I try to explain 3 points of my code in the 
commit message: motivation, approach and effects. Example:

https://github.com/avocado-framework/avocado/commit/661a9abbd21310ef7803ea0286fcb818cb93dfa9

If the commit is related to a trello card or an issue in github, I also 
add the line "Reference: <url>" to the commit message bottom. You can 
mention it in Pull Request message instead, but the main point is not to 
omit that information.

- If working on 'avocado' repository, this is the time to run 'make check'.

- Push your commit(s) to your fork:

  $ git push --set-upstream origin my_new_local_branch

- Create the Pull Request on github.

Now you're waiting for feedback on github Pull Request page. Once you 
get some, new versions of your code should not be force-updated. 
Instead, you should:

- Close the Pull Request on github.

- Create a new branch out of your previous branch, naming it with '_v2' 
in the end (this will further allow code-reviewers to simple run '$ git 
diff user_my_new_local_branch{,_v2}' to see what changed between versions):

  $ git checkout my_new_local_branch
  $ git checkout -b my_new_local_branch_v2

- Code and amend the commit. If you have more than one commit in the PR, 
you will probably need to rebase interactively to amend the right commits.

- Push your changes:

  $ git push --set-upstream origin my_new_local_branch_v2

- Create a new Pull Request for this new branch. In the PR message, 
point the previous PR and the changes this PR introduced when compared 
to the previous PRs. Example of PR message for a 'V2':

https://github.com/avocado-framework/avocado/pull/1228

After your PR gets merged, you can sync your local repository and your 
fork on github:

  $ git checkout master
  $ git pull upstream master
  $ git push

That's it. That's my personal workflow, what means it probably differs 
from what others developers are used to do, but the important here is to 
someway cover the good practices we have in the project.

Please feel free to comment and to add more information here.

Best,
-- 
apahim