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 g...@github.com:<username>/avocado-misc-tests.git
- Enter directory:
$ cd avocado-misc-tests/
- Setup upstream:
$ git remote add upstream
g...@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 ]
_______________________________________________
Avocado-devel mailing list
Avocado-devel@redhat.com
https://www.redhat.com/mailman/listinfo/avocado-devel
