From 7219f212c7fac274ce07b5dc35e1fa3b30da8f9d Mon Sep 17 00:00:00 2001 From: Ed Manlove Date: Thu, 18 Jan 2024 20:46:00 -0500 Subject: [PATCH 1/6] First pass on revising the CONTRIBUTING documentation --- CONTRIBUTING.rst | 42 +++++++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index de1a76316..3713f0409 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -3,16 +3,17 @@ Contribution guidelines These guidelines instruct how to submit issues and contribute code to the `SeleniumLibrary project`_. Other great ways to contribute include -answering questions and participating discussion on `robotframework-users`_ -mailing list and other forums as well as spreading the word about the -framework one way or the other. +answering questions and participating discussion on #seleniumlibrary channel +within the community `Robot Framework Slack`_, the `Robot Framework Forum`_ +and other forums as well as spreading the word about the framework one way +or the other. Submitting issues ================= Bugs and enhancements are tracked in the `issue tracker`_. If you are unsure if something is a bug or is a feature worth -implementing, you can first ask on `robotframework-users`_ list. This and +implementing, you can first ask with the `Robot Framework Slack`_. This and other similar forums, not the issue tracker, are also places where to ask general questions. @@ -88,15 +89,23 @@ We do, however, recommend to create dedicated branches for pull requests instead of creating them based on the master branch. This is especially important if you plan to work on multiple pull requests at the same time. -This project requires that pull request contains linear history of commits and -we do not allow that pull request contains merge commits or other noise. This helps -the review process and makes the maintenance easier for the project administrators. -Generally it is recommended to do `git pull --rebase` instead of the `git pull --merge` -when there is need pull changes from upstream. +This project asks that prior to making an enhancement pull request that you +discuss the enhancement with the team. We wish to avoid having you spend effort on an +ehancement that won't match with the project. We require that a pull request contains +linear history of commits and we do not allow that pull request contains merge commits +or other noise. This helps the review process and makes the maintenance easier for the +project administrators. Generally it is recommended to do `git pull --rebase` instead +of the `git pull --merge` when there is need pull changes from upstream. Coding conventions ------------------ +The SeleniumLibrary team is currently reviewing, revising, and updating +the coding conventions during Q1 2024. Knowing these coding conventions +are seen as a good practice, we are leaving these here as recommendations +in the mean time but are not forcing this as a requirement for accepting +pull requests. + SeleniumLibrary uses the general Python code conventions defined in `PEP-8`_. In addition to that, we try to write `idiomatic Python`_ and follow the `SOLID principles`_. with all new code. An important guideline @@ -184,9 +193,10 @@ tests Date: Thu, 18 Jan 2024 21:20:54 -0500 Subject: [PATCH 2/6] Minor corrections and verified and updated links --- CONTRIBUTING.rst | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 3713f0409..bfdadfd0e 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -3,10 +3,10 @@ Contribution guidelines These guidelines instruct how to submit issues and contribute code to the `SeleniumLibrary project`_. Other great ways to contribute include -answering questions and participating discussion on #seleniumlibrary channel -within the community `Robot Framework Slack`_, the `Robot Framework Forum`_ -and other forums as well as spreading the word about the framework one way -or the other. +answering questions and participating in discussions within the +#seleniumlibrary channel on the community `Robot Framework Slack`_, the +`Robot Framework Forum`_ and other channels as well as spreading the word +about the framework one way or the other. Submitting issues ================= @@ -107,7 +107,7 @@ in the mean time but are not forcing this as a requirement for accepting pull requests. SeleniumLibrary uses the general Python code conventions defined in -`PEP-8`_. In addition to that, we try to write `idiomatic Python`_ +`PEP-8`_. In addition to that, we try to write `idiomatic Python`_ or `"Pythonic" code`_ and follow the `SOLID principles`_. with all new code. An important guideline is that the code should be clear enough that comments are generally not needed. @@ -169,12 +169,12 @@ When submitting a pull request with a new feature or a fix, you should always include tests for your changes. These tests prove that your changes work, help prevent bugs in the future, and help document what your changes do. Depending an the change, you may need -``acceptance tests``\ *, ``unit tests``* or both. +``acceptance tests``\ *, ``unit tests`` or both. Make sure to run all of the tests before submitting a pull request to be sure that your changes do not break anything. If you can, test in multiple browsers and versions (Firefox, Chrome, IE, Edge etc). Pull requests -are also automatically tested on `Travis CI`_. +are also automatically tested on `GitHub Actions`_. Acceptance tests ~~~~~~~~~~~~~~~~ @@ -182,13 +182,13 @@ Acceptance tests Most of SeleniumLibrary's testing is done using acceptance tests that naturally use Robot Framework itself for testing. Every new functionality or fix should generally get one or more acceptance tests. +For more details on acceptance tests see `atest/README.rst`_. Unit tests ~~~~~~~~~~ Unit tests are great for testing internal logic and should be added when -appropriate. For more details see `Unit and acceptance -tests `__. +appropriate. For more details on unit tests see `utest/README.rst`_. Continuous integration ---------------------- @@ -208,7 +208,7 @@ Acknowledgments ~~~~~~~~~~~~~~~ If you have done any non-trivial change and would like to be credited, -remind us to add `acknowledge` tag to the issue. This way we will add +remind us to add ``acknowledge`` tag to the issue. This way we will add your name to the release notes, when next release is made. Resolving conflicts @@ -229,7 +229,8 @@ the same code as your changes. In that case you should .. _fork a repository: https://help.github.com/articles/fork-a-repo/ .. _use pull requests: https://help.github.com/articles/using-pull-requests .. _PEP-8: https://www.python.org/dev/peps/pep-0008/ -.. _idiomatic Python: http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html +.. _idiomatic Python: https://en.wikibooks.org/wiki/Python_Programming/Idioms +.. _"Pythonic" code: https://docs.python-guide.org/writing/style/ .. _SOLID principles: https://en.wikipedia.org/wiki/SOLID_(object-oriented_design) .. _PEP-257: https://www.python.org/dev/peps/pep-0257/ .. _invoke: http://www.pyinvoke.org/ @@ -239,4 +240,4 @@ the same code as your changes. In that case you should .. _sync your fork: https://help.github.com/articles/syncing-a-fork/ .. _resolve conflicts: https://help.github.com/articles/resolving-a-merge-conflict-from-the-command-line .. _Black: https://github.com/psf/black -.. _flake8: https://gitlab.com/pycqa/flake8 \ No newline at end of file +.. _flake8: https://github.com/PyCQA/flake8 \ No newline at end of file From 1b77f672a7454850db6fea48a7cd43e3b08d986c Mon Sep 17 00:00:00 2001 From: Ed Manlove Date: Thu, 18 Jan 2024 21:25:13 -0500 Subject: [PATCH 3/6] Corrected link to utest/atest READMEs --- BUILD.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/BUILD.rst b/BUILD.rst index 9033fdaa4..ea33b0860 100644 --- a/BUILD.rst +++ b/BUILD.rst @@ -64,7 +64,8 @@ Testing ------- Make sure that adequate tests are executed before releases are created. -See ``_ for details. +For more information about unit tests see ``_ or for +acceptance tests see ``_. Preparation ----------- From fa0416f6911bc5c5baee0ef66dda4b0fdbcf4480 Mon Sep 17 00:00:00 2001 From: Ed Manlove Date: Thu, 18 Jan 2024 21:39:48 -0500 Subject: [PATCH 4/6] A few more corrections --- CONTRIBUTING.rst | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index bfdadfd0e..d4aca206d 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -154,7 +154,7 @@ individual keywords. - All new enhancements or changes should have a note telling when the change was introduced. Often adding something like - ``New in SeleniumLibray 1.8.`` is enough. + ``New in SeleniumLibrary 1.8.`` is enough. Keyword documentation can be easily created using `invoke`_ task:: @@ -168,8 +168,8 @@ Tests When submitting a pull request with a new feature or a fix, you should always include tests for your changes. These tests prove that your changes work, help prevent bugs in the future, and help document what -your changes do. Depending an the change, you may need -``acceptance tests``\ *, ``unit tests`` or both. +your changes do. Depending an the change, you may need ``acceptance tests``, +``unit tests`` or both. Make sure to run all of the tests before submitting a pull request to be sure that your changes do not break anything. If you can, test in @@ -182,21 +182,24 @@ Acceptance tests Most of SeleniumLibrary's testing is done using acceptance tests that naturally use Robot Framework itself for testing. Every new functionality or fix should generally get one or more acceptance tests. -For more details on acceptance tests see `atest/README.rst`_. +For more details on acceptance tests and how to run the acceptance tests, +see `atest/README.rst`_. Unit tests ~~~~~~~~~~ Unit tests are great for testing internal logic and should be added when -appropriate. For more details on unit tests see `utest/README.rst`_. - +appropriate. For more details on unit tests and running them, see +`utest/README.rst`_. +q Continuous integration ---------------------- -SeleniumLibrary use GitHub Actions as it's continuous integration (CI) server. -For more details about how to run the tests and how `GitHub Actions`_ -integration is implemented can be found with the `atest/README.rst`_ for -acceptance tests and `utest/README.rst`_ for unit tests. +SeleniumLibrary uses GitHub Actions as it's continuous integration (CI) server. + +.. ToDo: re-add when explanation of GitHUb Actions is written + More details about how `GitHub Actions`_ integration is implemented can be + found within `<.github/CI/README.rst>. Finalizing pull requests ------------------------ From e6684c709cdc589b816764b2dcc8602b6c6ce257 Mon Sep 17 00:00:00 2001 From: Ed Manlove Date: Thu, 18 Jan 2024 21:40:48 -0500 Subject: [PATCH 5/6] Minor change --- CONTRIBUTING.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index d4aca206d..54ac22cf1 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -191,7 +191,7 @@ Unit tests Unit tests are great for testing internal logic and should be added when appropriate. For more details on unit tests and running them, see `utest/README.rst`_. -q + Continuous integration ---------------------- From 606aa81837aa3b2a51b23503ac3aaf1ba37ba200 Mon Sep 17 00:00:00 2001 From: Ed Manlove Date: Thu, 18 Jan 2024 21:56:22 -0500 Subject: [PATCH 6/6] Added note about extending the library for enhancements .. and some minor corrections --- CONTRIBUTING.rst | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 54ac22cf1..ffb9d6ff8 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -13,12 +13,12 @@ Submitting issues Bugs and enhancements are tracked in the `issue tracker`_. If you are unsure if something is a bug or is a feature worth -implementing, you can first ask with the `Robot Framework Slack`_. This and +implementing, you can first ask within the `Robot Framework Slack`_. This and other similar forums, not the issue tracker, are also places where to ask general questions. -Before submitting a new issue, it is always a good idea to check is the -same bug or enhancement already reported. If it is, please add your +Before submitting a new issue, it is always a good idea to check if the +same bug or enhancement is already reported. If it is, please add your comments to the existing issue instead of creating a new one. Reporting bugs @@ -44,9 +44,11 @@ Enhancement requests Describe the new feature and use cases for it in as much detail as possible in an issue. Especially with larger enhancements, be prepared to -contribute the code in form of a pull request as explained below or to +contribute the code in the form of a pull request as explained below or to pay someone for the work. Consider also would it be better to implement this -functionality as a separate library outside the SeleniumLibrary. +functionality as a separate library outside the SeleniumLibrary. One option +here is to extend SeleniumLibrary using the public API or plug-in api. Please +see `extending documentation`_ for more details. Code contributions ================== @@ -226,6 +228,7 @@ the same code as your changes. In that case you should .. _Robot Framework Forum: https://forum.robotframework.org/c/libraries/lib-seleniumlibrary/11 .. _issue tracker: https://github.com/robotframework/SeleniumLibrary/issues .. _(SSCCE): http://sscce.org +.. _extending documentation: https://github.com/robotframework/SeleniumLibrary/blob/master/docs/extending/extending.rst .. _GitHub account: https://github.com/ .. _Git: https://git-scm.com .. _set up Git: https://help.github.com/articles/set-up-git/