robotframework 3.0.4rc1__tar.gz → 7.2rc1__tar.gz

robotframework-7.2rc1/AUTHORS.rst

@@ -0,0 +1,108 @@
+Robot Framework contributors
+============================
+
+This file lists contributors to Robot Framework during the time it was
+developed at Nokia Networks. There are both `core team members`_ as well
+as `other contributors`_.
+
+Nowadays contributors are acknowledged separately in the release notes
+and this file is not anymore updated. Contributors can also be found easily
+via GitHub__.
+
+__ https://github.com/robotframework/robotframework/graphs/contributors
+
+Core team members
+-----------------
+
+The members of the Robot Framework core team during the Nokia Networks years
+2005 - 2015.
+
+===========================    ===========
+         Name                     Years
+===========================    ===========
+Pekka Klärck (né Laukkanen)    2005 - 2015
+Petri Haapio                   2005 - 2008
+Juha Rantanen                  2005 - 2011
+Lasse Koskela                  2005 - 2006
+Janne Härkönen                 2006 - 2012
+Sami Honkonen                  2006 - 2007
+Antti Tuomaala                 2006
+Ran Nyman                      2007 - 2010
+Heikki Hulkko                  2007 - 2009
+Anna Tevaniemi                 2008
+Kari Husa                      2009 - 2011
+Jussi Malinen                  2010 - 2015
+Mikko Korpela                  2010 - 2014
+Ismo Aro                       2010 - 2012
+Ilmari Kontulainen             2010 - 2013
+Tommi Asiala                   2012
+Mika Hänninen                  2012 - 2013
+Tatu Kairi                     2012 - 2014
+Anssi Syrjäsalo                2013
+Janne Piironen                 2013 - 2014
+===========================    ===========
+
+Other contributors
+------------------
+
+External contributors after Robot Framework was open sourced in 2008.
+As already mentioned above, this list is not anymore updated.
+
+===========================    ===============================================
+         Name                                    Contribution
+===========================    ===============================================
+Elisabeth Hendrickson          | Quick Start Guide (2.0)
+Marcin Michalak                | String library (2.1)
+Chris Prinos                   | reST (HTML) support (2.1)
+                               | How-to debug execution with `pdb` (2.7.6)
+Régis Desgroppes               | Fixing installation paths (2.1.3)
+                               | xUnit compatible outputs (2.5.5)
+Robert Spielmann               | Report background colors (2.5)
+Xie Yanbo                      | Alignment of east asian characters (2.5.3)
+JSXGraph Developers            | JSXGraph tool and license changes for it (2.6)
+Imran                          | Template names to listener API (2.6)
+                               | Suite source to listener API (2.7)
+Tatu Aalto                     | Get Time keyword enhancement (2.7.5)
+Eemeli Kantola                 | Fix for non-breaking spaces (2.7.5)
+Martti Haukijärvi              | IronPython support to Screenshot library (2.7.5)
+Guy Kisel                      | How-to use decorators when creating libraries (2.7.7)
+                               | BuiltIn.Log pprint support (2.8.6)
+                               | New pattern matching keywords in Collections (2.8.6)
+                               | Keyword/variable not found recommendations (2.8.6)
+                               | Tidy ELSE and ELSE IF onto separate lines (2.8.7)
+                               | Initial contribution guidelines (2.9, #1805)
+Mike Terzo                     | Better connection errors to Remote library (2.7.7)
+Asko Soukka                    | reST (plain text) support (2.8.2)
+Vivek Kumar Verma              | reST (plain text) support (2.8.2)
+Stefan Zimmermann              | `**kwargs` support for dynamic libraries (2.8.2)
+                               | `**kwargs` support for Java libraries (2.8.3)
+                               | `*varargs` support using java.util.List (2.8.3)
+Mirel Pehadzic                 | Terminal emulation for Telnet library (2.8.2)
+Diogo Sa-Chaves De Oliveira    | Terminal emulation for Telnet library (2.8.2)
+Lionel Perrin                  | Giving custom seed to --randomize (2.8.5)
+Michael Walle                  | Telnet.Write Control Character keyword (2.8.5)
+                               | Telnet.Read Until Prompt strip_prompt option (2.8.7)
+                               | String.Strip String (3.0)
+Tero Kinnunen                  | BDD 'But' prefix ignored (2.8.7)
+Heiko Thiery                   | Enable log level config option for TelnetLibrary (2.8.7)
+Nicolae Chedea                 | Float parameters in FOR IN RANGE (2.8.7)
+Jared Hellman                  | Custom keyword names (2.9)
+                               | Embedded arguments for library keywords (2.9)
+Vinicius K. Ruoso              | Support multiple listeners per library (2.9)
+                               | Allowing control over connection timeout in Telnet library (2.9.2)
+                               | Suppress docutils errors/warnings with reST format (2.9.2)
+Joseph Lorenzini               | Exposed ERROR log level for keywords (2.9)
+Guillaume Grossetie            | Less flashy report and log styles (2.9, #1943)
+Ed Brannin                     | `FOR ... IN ZIP`, `FOR ... IN ENUMERATE` (2.9, #1989)
+Moon SungHoon                  | String.Get Regexp Matches keyword (2.9, #1985)
+Hélio Guilherme                | Support partial match with String.Get Lines Matching Regexp (2.9, #1836)
+Jean-Charles Deville           | Make variable errors not exit `Runner keywords` (2.9, #1869)
+Laurent Bristiel               | Convert examples in User Guide to plain text format (2.9, #1972)
+Tim Orling                     | IronPython support for `Dialogs` library (2.9.2, #1235)
+Jozef Behran                   | Fix `${TEST_MESSAGE}` to reflect current test message (3.0, #2188)
+Joong-Hee Lee                  | Extend 'Repeat Keyword' to support timeout (3.0, #2245)
+Anton Nikitin                  | Should (Not) Contain Any (3.0.1, #2120)
+Yang Qian                      | Support to copy/deepcopy model objects (3.0.1, #2483)
+Chris Callan                   | Case-insensitivity support to various comparison keywords (3.0.1, #2439)
+Benjamin Einaudi               | Add `--rerunfailedsuites` option (3.0.1, #2117)
+===========================    ===============================================

{robotframework-3.0.4rc1 → robotframework-7.2rc1}/BUILD.rst

@@ -36,9 +36,9 @@ Many steps are automated using the generic `Invoke <http://pyinvoke.org>`_
 tool with a help by our `rellu <https://github.com/robotframework/rellu>`_
 utilities, but also other tools and modules are needed. A pre-condition is
 installing all these, and that's easiest done using `pip
-<http://pip-installer.org>`_ and the provided `<requirements-build.txt>`_ file::
+<http://pip-installer.org>`_ and the provided `<requirements-dev.txt>`_ file::
 
-    pip install -r requirements-build.txt
+    pip install -r requirements-dev.txt
 
 Using Invoke
 ~~~~~~~~~~~~
@@ -66,10 +66,17 @@ Testing
 Make sure that adequate tests are executed before releases are created.
 See `<atest/README.rst>`_ for details.
 
+If output.xml `schema <doc/schema/README.rst>`_ has changed, remember to
+run tests also with `full schema validation`__ enabled::
+
+    atest/run.py --schema-validation
+
+__ https://github.com/robotframework/robotframework/tree/master/atest#schema-validation
+
 Preparation
 -----------
 
-1. Check that you are on the master branch and have nothing left to commit,
+1. Check that you are on the right branch and have nothing left to commit,
    pull, or push::
 
       git branch
@@ -86,35 +93,40 @@ Preparation
 
       VERSION=<version>
 
-   For example, ``VERSION=3.0.1`` or ``VERSION=3.1a2``.
+   For example, ``VERSION=7.1.1`` or ``VERSION=7.2a2``. No ``v`` prefix!
 
 Release notes
 -------------
 
-1. Set GitHub user information into shell variables to ease copy-pasting the
-   following command::
+1. Create a personal `GitHub access token`__ to be able to access issue tracker
+   programmatically. The token needs only the ``repo/public_repo`` scope.
+
+2. Set GitHub user information into shell variables to ease running the
+   ``invoke release-notes`` command in the next step::
 
       GITHUB_USERNAME=<username>
-      GITHUB_PASSWORD=<password>
+      GITHUB_ACCESS_TOKEN=<token>
 
-   Alternatively, supply the credentials when running that command.
+   ``<username>`` is your normal GitHub user name and ``<token>`` is the personal
+   access token generated in the previous step. Alternatively this information can
+   be given when running the command in the next step.
 
-2. Generate a template for the release notes::
+3. Generate a template for the release notes::
 
-      invoke release-notes -w -v $VERSION -u $GITHUB_USERNAME -p $GITHUB_PASSWORD
+      invoke release-notes -w -v $VERSION -u $GITHUB_USERNAME -p $GITHUB_ACCESS_TOKEN
 
    The ``-v $VERSION`` option can be omitted if `version is already set
    <Set version_>`__. Omit the ``-w`` option if you just want to get release
    notes printed to the console, not written to a file.
 
-   When generating release notes for a preview release like ``3.0.2rc1``,
+   When generating release notes for a preview release like ``7.2rc1``,
    the list of issues is only going to contain issues with that label
    (e.g. ``rc1``) or with a label of an earlier preview release (e.g.
    ``alpha1``, ``beta2``).
 
-2. Fill the missing details in the generated release notes template.
+4. Fill the missing details in the generated release notes template.
 
-3. Make sure that issues have correct information:
+5. Make sure that issues have correct information:
 
    - All issues should have type (bug, enhancement or task) and priority set.
      Notice that issues with the task type are automatically excluded from
@@ -127,26 +139,28 @@ Release notes
    issue tracker than in the generated release notes. This allows re-generating
    the list of issues later if more issues are added.
 
-4. Add, commit and push::
+6. Add, commit and push::
 
       git add doc/releasenotes/rf-$VERSION.rst
       git commit -m "Release notes for $VERSION" doc/releasenotes/rf-$VERSION.rst
       git push
 
-5. Update later if necessary. Writing release notes is typically the biggest
+7. Update later if necessary. Writing release notes is typically the biggest
    task when generating releases, and getting everything done in one go is
    often impossible.
 
+__ https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token
+
 Set version
 -----------
 
-1. Set version information in `<src/robot/version.py>`_ and in `<pom.xml>`_::
+1. Set version information in `<src/robot/version.py>`_ and `<setup.py>`_::
 
       invoke set-version $VERSION
 
 2. Commit and push changes::
 
-      git commit -m "Updated version to $VERSION" src/robot/version.py pom.xml
+      git commit -m "Updated version to $VERSION" src/robot/version.py setup.py
       git push
 
 Tagging
@@ -175,71 +189,39 @@ Creating distributions
 
       invoke clean
 
-3. Create source distribution::
-
-      python setup.py sdist
-      ls -l dist
-
-   Distributions can be tested locally if needed.
-
-4. Upload distributions to PyPI::
-
-      twine upload dist/*
+3. Build `libdoc.html`::
 
-5. Verify that project the page at `PyPI
-   <https://pypi.python.org/pypi/robotframework>`_ looks good.
+      npm run build --prefix src/web/
 
-6. Test installation (add ``--pre`` with pre-releases)::
+   This step can be skipped if there are no changes to Libdoc. Prerequisites
+   are listed in `<src/web/README.md>`_.
 
-      pip install --upgrade robotframework
+4. Create and validate source distribution and `wheel <https://pythonwheels.com>`_::
 
-7. JAR distribution
-
-   - Create::
-
-       invoke jar
-
-   - Test that JAR is not totally borken::
-
-       java -jar dist/robotframework-$VERSION.jar --version
-       java -jar dist/robotframework-$VERSION.jar atest/testdata/misc/pass_and_fail.robot
-
-8. Upload JAR to Sonatype
-
-   - Sonatype offers a service where users can upload JARs and they will be synced
-     to the maven central repository. Below are the instructions to upload the JAR.
-
-   - Prequisites:
-
-      - Install maven
-      - Create a `Sonatype account`__
-      - Add these lines (filled with the Sonatype account information) to your ``settings.xml``::
+      python setup.py sdist bdist_wheel
+      ls -l dist
+      twine check dist/*
 
-            <servers>
-                <server>
-                    <id>sonatype-nexus-staging</id>
-                    <username></username>
-                    <password></password>
-                </server>
-            </servers>
+   Distributions can be tested locally if needed.
 
-      - Create `a PGP key`__
-      - Apply for `publish rights`__ to org.robotframework project. This will
-        take some time from them to accept.
+5. Upload distributions to PyPI::
 
+      twine upload dist/*
 
-   - Run command::
+6. Verify that project pages at `PyPI
+   <https://pypi.python.org/pypi/robotframework>`_ look good.
 
-        mvn gpg:sign-and-deploy-file -Dfile=dist/robotframework-$VERSION.jar -DpomFile=pom.xml -Durl=http://oss.sonatype.org/service/local/staging/deploy/maven2/ -DrepositoryId=sonatype-nexus-staging
+7. Test installation::
 
-   - Go to https://oss.sonatype.org/index.html#welcome, log in with Sonatype credentials, find the staging repository and do close & release
-   - After that, the released JAR is synced to Maven central within an hour.
+      pip install --pre --upgrade robotframework
 
-__ https://issues.sonatype.org/secure/Dashboard.jspa
-__ http://central.sonatype.org/pages/working-with-pgp-signatures.html
-__ https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide
+8. Documentation
 
-9. Documentation
+   - For a reproducible build, set the ``SOURCE_DATE_EPOCH``
+     environment variable to a constant value, corresponding to the
+     date in seconds since the Epoch (also known as Epoch time).  For
+     more information regarding this environment variable, see
+     https://reproducible-builds.org/docs/source-date-epoch/.
 
    - Generate library documentation::
 
@@ -253,19 +235,19 @@ __ https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Us
 
         git checkout gh-pages
         invoke add-docs $VERSION --push
-        git checkout master
+        git checkout master    # replace master with v*-maintenance if needed!
 
 Post actions
 ------------
 
 1. Back to master if needed::
 
-      git checkout master
+      git checkout master    # replace master with v*-maintenance if needed!
 
 2. Set dev version based on the previous version::
 
       invoke set-version dev
-      git commit -m "Back to dev version" src/robot/version.py pom.xml
+      git commit -m "Back to dev version" src/robot/version.py setup.py
       git push
 
    For example, ``1.2.3`` is changed to ``1.2.4.dev1`` and ``2.0.1a1``
@@ -297,7 +279,7 @@ Announcements
 3. ``#devel`` and ``#general`` channels on Slack.
 
 4. `Robot Framework LinkedIn
-   <https://www.linkedin.com/groups/Robot-Framework-3710899>`_ group.
+   <https://www.linkedin.com/groups/3710899/>`_ group.
 
 5. Consider sending announcements, at least with major releases, also to other
    forums where we want to make the framework more well known. For example:

{robotframework-3.0.4rc1 → robotframework-7.2rc1}/CONTRIBUTING.rst

@@ -1,8 +1,9 @@
 Contribution guidelines
 =======================
 
-These guidelines instruct how to submit issues and contribute code to the
-`Robot Framework project <https://github.com/robotframework/robotframework>`_.
+These guidelines instruct how to submit issues and contribute code or
+documentation to the `Robot Framework project
+<https://github.com/robotframework/robotframework>`_.
 There are also many other projects in the larger `Robot Framework ecosystem
 <http://robotframework.org>`_ that you can contribute to. If you notice
 a library or tool missing, there is hardly any better way to contribute
@@ -12,6 +13,11 @@ answering questions and participating discussion on `robotframework-users
 and other forums, as well as spreading the word about the framework one way or
 the other.
 
+These guidelines expect readers to have a basic knowledge about open source
+as well as why and how to contribute to open source projects. If you are
+totally new to these topics, it may be a good idea to look at the generic
+`Open Source Guides <https://opensource.guide/>`_ first.
+
 .. contents::
    :depth: 2
    :local:
@@ -25,7 +31,7 @@ unsure if something is a bug or is a feature worth implementing, you can
 first ask on `robotframework-users`_ mailing list, on `IRC
 <http://webchat.freenode.net/?channels=robotframework&prompt=1>`_
 (#robotframework on irc.freenode.net), or on `Slack
-<https://robotframework-slack.herokuapp.com>`_. These and other similar
+<https://robotframework-slack-invite.herokuapp.com>`_. These 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
@@ -41,8 +47,8 @@ and preferably also reproduce it. Key things to have in good bug report:
 1. Version information
 
    - Robot Framework version
-   - Python interpreter type (Python, Jython or IronPython) and version
-   - Operating system name and version
+   - Python interpreter version
+   - Operating system and its version
 
 2. Steps to reproduce the problem. With more complex problems it is often
    a good idea to create a `short, self contained, correct example (SSCCE)
@@ -58,7 +64,7 @@ Enhancement requests
 
 Describe the new feature and use cases for it in as much detail as possible.
 Especially with larger enhancements, be prepared to contribute the code
-in form of a pull request as explained below or to pay someone for the work.
+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
 tool outside the core framework.
 
@@ -77,15 +83,27 @@ Often you already have a bug or an enhancement you want to work on in your
 mind, but you can also look at the `issue tracker`_ to find bugs and
 enhancements submitted by others. The issues vary significantly in complexity
 and difficulty, so you can try to find something that matches your skill level
-and knowledge.
+and knowledge. There are two specific labels to look for when looking for
+something to contribute:
+
+`good first issue`__
+   These issues typically do not require any knowledge of Robot Framework
+   internals and are generally easy to implement or fix. Thus these issues
+   are especially good for new contributors.
+
+`help wanted`__
+   These issues require external help to get implemented or fixed.
+
+__ https://github.com/robotframework/robotframework/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22
+__ https://github.com/robotframework/robotframework/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22
 
 Pull requests
 ~~~~~~~~~~~~~
 
 On GitHub pull requests are the main mechanism to contribute code. They
-are easy to use both for the contributor and for person accepting
+are easy to use both for the contributor and for the person accepting
 the contribution, and with more complex contributions it is easy also
-for others to join the discussion. Preconditions for creating a pull
+for others to join the discussion. Preconditions for creating pull
 requests are having a `GitHub account <https://github.com/>`_,
 installing `Git <https://git-scm.com>`_ and forking the
 `Robot Framework project`_.
@@ -94,8 +112,8 @@ GitHub has good articles explaining how to
 `set up Git <https://help.github.com/articles/set-up-git/>`_,
 `fork a repository <https://help.github.com/articles/fork-a-repo/>`_ and
 `use pull requests <https://help.github.com/articles/using-pull-requests>`_
-and we do not go through them in more detail. We do, however,
-recommend to create dedicated branches for pull requests instead of creating
+and we do not go through them in more detail. We do, however, recommend to
+create dedicated topic 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.
 
@@ -118,6 +136,18 @@ All code, including test code, must be compatible with all supported Python
 interpreters and versions. Most importantly this means that the code must
 support both Python 2 and Python 3.
 
+Line length
+'''''''''''
+
+Maximum line length with Python code, including docstrings and comments, is 88
+characters. This is also what `Black <https://pypi.org/project/black/>`__ uses
+by default and `their documentation
+<https://black.readthedocs.io/en/stable/the_black_code_style.html#line-length>`__
+explains why. Notice that we do not have immediate plans to actually take Black
+into use but we may consider that later.
+
+With Robot Framework tests the maximum line length is 100.
+
 Whitespace
 ''''''''''
 
@@ -125,6 +155,8 @@ We are pretty picky about using whitespace. We follow `PEP-8`_ in how to use
 blank lines and whitespace in general, but we also have some stricter rules:
 
 - No blank lines inside functions.
+- No blank lines between a class declaration and class attributes or between
+  attributes.
 - Indentation using spaces, not tabs.
 - No trailing spaces.
 - No extra empty lines at the end of the file.
@@ -179,11 +211,24 @@ and follow these guidelines:
   not trivial.
 
 - All new enhancements or changes should have a note telling when the change
-  was introduced. Often adding something like ``New in Robot Framework 2.9.``
+  was introduced. Often adding something like ``New in Robot Framework 3.1.``
   is enough.
 
-Library documentation can be easily created using `<doc/libraries/lib2html.py>`_
-script. Resulting docs should be verified before the code is committed.
+Library documentation can be generated using `Invoke <http://pyinvoke.org>`_
+by running command
+
+::
+
+    invoke library-docs <name>
+
+where ``<name>`` is the name of the library or its unique prefix. Run
+
+::
+
+    invoke --help library-docs
+
+for more information see `<BUILD.rst>`_ for details about installing and
+using Invoke.
 
 API documentation
 '''''''''''''''''
@@ -211,13 +256,13 @@ 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
+do. Depending on 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 multiple
-environments and interpreters (Windows, Linux, OS X, Python, Jython,
-IronPython, Python 3, etc). Pull requests are also automatically tested on
+environments and interpreters (Windows, Linux, OS X, different Python
+versions etc). Pull requests are also automatically tested on
 continuous integration.
 
 Executing changed code
@@ -248,41 +293,3 @@ Unit tests
 
 Unit tests are great for testing internal logic and should be added when
 appropriate. For more details see `<utest/README.rst>`_.
-
-Finalizing pull requests
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Once you have code, documentation and tests ready, it is time to finalize
-the pull request.
-
-AUTHORS.txt
-'''''''''''
-
-If you have done any non-trivial change and would like to be credited,
-add yourself to `<AUTHORS.txt>`_ file.
-
-Resolving conflicts
-'''''''''''''''''''
-
-Conflicts can occur if there are new changes to the master that touch the
-same code as your changes. In that case you should `sync your fork
-<https://help.github.com/articles/syncing-a-fork>`_ and `resolve conflicts
-<https://help.github.com/articles/resolving-a-merge-conflict-from-the-command-line>`_
-to allow for an easy merge.
-
-The most common conflicting file is the aforementioned `AUTHORS.txt`_, but
-luckily fixing those conflicts is typically easy.
-
-Squashing commits
-'''''''''''''''''
-
-If the pull request contains multiple commits, it is recommended that you
-squash them into a single commit before the pull request is merged.
-See `Squashing Github pull requests into a single commit
-<http://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit>`_
-article for more details about why and how.
-
-Squashing is especially important if the pull request contains lots of
-temporary commits and changes that have been later reverted or redone.
-Squashing is not needed if the commit history is clean and individual
-commits are meaningful alone.