From 6e7a96817b66ff5215558ab8fed0ee3a29d16020 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Tue, 9 Mar 2021 18:28:35 +0100 Subject: [PATCH] Add CONTRIBUTING.md --- CONTRIBUTING.md | 181 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d63fb55 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,181 @@ +# Contributing + +Contributing to this repository, we follow [Ansible Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) in all our interactions within the project. + +## Issue tracker + +Whether you are looking for an opportunity to contribute or you found a bug and already know how to solve it, please go to the [issue tracker](https://github.com/ansible-collections/community.mysql/issues). +There you can find feature ideas to implement, reports about bugs to solve, or submit an issue to discuss your idea before implementing it which can help choose a right direction initially and potentially save a lot of time and effort. +Also somebody can already start discussing or working on implementing the same or similar idea, +so you can cooperate to create a better solution together. + +## Open pull requests + +Look through currently [open pull requests](https://github.com/ansible-collections/community.mysql/pulls). +You can help by reviewing them. There can be good pull requests which are not merged only because there are a lack of reviews. Also there can be worth, reviewed, but abandoned ones, which you could politely ask the original authors to complete yourself. +And it is always worth saying that good reviews are often more valuable than pull requests themselves. + +## Looking for an idea to implement + +First, see the paragraphs above. + +If you came up with a new feature, it is always worth creating an issue +before starting to write code to discuss the idea with the community first. + +## Step-by-step guide how to get into development quickly. + +We assume you use Linux as a work environment (you can use a virtual machine as well). + +1. Install ``docker``, launch it. + +2. Clone the [ansible-core](https://github.com/ansible/ansible) repository: +```bash +git clone https://github.com/ansible/ansible.git +``` +3. Go to the cloned repository and prepare the environment: +```bash +cd ansible && source hacking/env-setup +cd ~ +``` + +4. Fork the ``community.mysql`` repository via the GitHub web interface. + +5. Clone the forked repository from your profile: +```bash +git clone https://github.com/YOURACC/community.mysql.git +``` + +6. Create the following directories in your home directory: +```bash +mkdir -p ~/ansible_collections/community +``` + +7. Move the cloned repository: +```bash +mv community.mysql ~/ansible_collections/community/mysql +``` + +8. Go there: +```bash +cd ~/ansible_collections/community/mysql +``` + +9. Be sure you are in the main branch: +```bash +git status +``` + +10. Show remotes. There should be the ``origin`` repository only: +```bash +git remote -v +``` + +11. Add the ``upstream`` repository: +```bash +git remote add upstream https://github.com/ansible-collections/community.mysql.git +``` + +12. Update your local ``main`` branch: +```bash +git fetch upstream +git merge upstream/main +``` + +13. Create a branch for your changes: +```bash +git branch -b name_of_my_branch +``` + +14. In any case, a good approach is to start from writing [integration tests](https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html). + +Briefly, all integration tests are just Ansible roles and are stored in ``tests/integration/targets`` subdirectories. +Tasks in the test roles invoke a module or plugin and check the result using the ``assert`` statement. +You are interested in a subdirectory containing a name of module you are going to change. +For example, if you are fixing the ``mysql_user`` module, its tests are in ``tests/integration/targets/test_mysql_user/tasks`` + +There is the ``main.yml`` file which includes other files. +Look for a suitable one to integrate your tests or create and include a dedicated one. +You can use one of the existing as a draft. + +When fixing a bug, write a task which reproduces the bug from the issue. +If there is no example in the bug report, ask a reporter to provide the problematic part. +Also can be useful to ask the reporter to provide the traceback if not provided - they need to run the task with -vvv argument. + +Put the reported case in the tests, then run integration tests with the following command: +```bash +ansible-test integration test_mysql_user --docker -vvv > ~/test.log +``` +If the tests do not want to run, first, check you complete step 3 of this guide. + +If the tests ran successfully, there are usually two possible outcomes: +a) If the bug has not appeared and the tests have passed successfully, ask the reporter to provide more details. The bug can be not a bug actually or can relate to a particular software version used or specifics of local environment configuration. + +b) The bug has appeared and the tests has failed as expected showing the reported symptoms. + +15. Fix the bug. + +16. Run ``flake8``: +```bash +flake8 /path/to/changed/file +``` +It is worth installing and running and ``flake8`` against the changed file(s) first. +It shows unused imports, which is not shown by sanity tests, as well as other common issues. + +17. Run sanity tests: +```bash +ansible-test sanity /path/to/changed/file --docker +``` +If they failed, look at the output carefully - it is usually very informative and helps to identify a problem line quickly. +Sanity failings usually relate to wrong code and documentation formatting. + +18. Run integration tests: +```bash +ansible-test integration test_mysql_user --docker -vvv > ~/test.log +``` + +There are two possible outcomes: +a) They have failed. Look into the ``test.log``. +Errors are usually at the end of the file. +Fix the problem place in the code and run again. +Repeat the cycle until the tests pass. + +b) They have passed. Remember they failed originally? Our congratulations! You has probably fixed the bug, though we hope not introducing a couple of new ones;) + +19. Commit your changes with an informative but short commit message: +```bash +git add /path/to/changed/file +git commit -m "mysql_user: fix crash when ..." +``` + +20. Push the branch to the ``origin`` (your fork): +```bash +git push origin name_of_my_branch +``` + +21. Go to the ``upstream`` (http://github.com/ansible-collections/community.mysql.git + +22. Go to ``Pull requests`` tab and create a pull request. + +GitHub is tracking your fork, so it should see the new branch in it and automatically offer +to create a pull request. Sometimes GitHub does not do it and you should click the ``New pull request`` button yourself. +Then choose ``compare across forks`` under the ``Compare changes`` title. +Choose your repository and the new branch you pushed in the right drop-down list. +Confirm. Fill out the pull request template with all information you want to mention. +Put "Fixes + link to the issue" in the pull request's description. +Put "[WIP] + short description" in the pull request's title. +Click ``Create pull request``. + +23. Add a [changelog fragment](https://docs.ansible.com/ansible/latest/community/development_process.html#changelogs). It will be published in release notes, so users will know about the fix. + +24. The CI tests will run automatically on Red Hat infrastructure after every commit. + +You will see their status in the bottom of your pull request. +If they are green, remove "[WIP]" from the title. Mention the issue reporter in a comment and let contributors know that the pull request is "Ready for review". + +25. Wait for reviews. + +26. If the pull request looks good to the community, committers will merge it. + +For details, refer to the [Ansible developer guide](https://docs.ansible.com/ansible/latest/dev_guide/index.html). + +If you find any inconsistencies or places in this document which can be improved, feel free to raise an issue or pull request to fix it.