[Avocado-devel] Collaboration Workflow

[Cleber Rosa]

On 05/31/2016 06:09 AM, Amador Pahim wrote:
> 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.
>

Amador,

Thanks for cooking this sort of tutorial for new contributors!  I 
imagine it's going to be very useful.

Once it matures, that is, if people add some extra touches and tips to 
it, please merge this into our contribution guide so that's more 
persistent and easy to find.

We can/should even advertise this section more aggressively, say, in the 
README file.

Cheers,
- Cleber.

> Best,

-- 
Cleber Rosa
[ Sr Software Engineer - Virtualization Team - Red Hat ]
[ Avocado Test Framework - avocado-framework.github.io ]