You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/contributing.rst
+27-16Lines changed: 27 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,18 +12,15 @@ How to contribute Feedback, Issues, Thoughts and Ideas
12
12
13
13
Please use the `issues`_ page to report issues or post ideas for enhancement.
14
14
15
-
Join our `Webex Python SDK - Python Community Contributors <https://eurl.io/#BJ0A8gfOQ>`_ Webex space to join the conversation with other contributors to this project.
16
-
17
-
18
15
19
16
Interested in Contributing Code?
20
17
================================
21
18
22
19
23
-
Developer Scripts
24
-
-----------------
20
+
Common Developer Tasks
21
+
----------------------
25
22
26
-
We have created some scripts to automate everyday actions needed when working on the project. Please see the `script`_ directory, and it's README for more information.
23
+
See the project's `Makefile` targets for a list of common developer tasks, which you can run by simply running `make <target>` from the repository root directory.
27
24
28
25
29
26
Notes on the Test Suite
@@ -41,19 +38,28 @@ Contributing Code
41
38
42
39
2. Fork a copy of the `repository`_ and clone your forked repository to your development environment.
43
40
44
-
3. Run ``script/setup`` to install the development dependencies and setup your environment.
41
+
3. Use the ``setup`` target to install the project dependencies and setup your environment for development.
42
+
43
+
.. code-block:: bash
44
+
45
+
make setup
45
46
46
-
4. Configure the following environment variables in your development environment:
47
+
4. Add your code to your forked repository.
47
48
48
-
* ``WEBEX_ACCESS_TOKEN`` - Your test account's Webex access token.
49
+
If you are creating some new feature or functionality (excellent!), please also write tests to verify that your code works as expected.
49
50
50
-
5. Add your code to your forked repository.
51
+
5. Please format your code and make sure your code passes the linter.
51
52
52
-
If you are creating some new feature or functionality (excellent!), please also write a `test`_ to verify that your code works as expected.
53
+
.. code-block:: bash
53
54
54
-
6. We follow `PEP8`_ reasonably strictly for this project. Please make sure your code passes the linter.
55
+
make format
56
+
make lint
55
57
56
-
Run ``script/test lint`` or simply run ``flake8`` from the project root.
58
+
6. If you running the test suite locally, ensure your code passes all of the default tests. Use the ``test`` target and ensure all tests execute successfully.
59
+
60
+
.. code-block:: bash
61
+
62
+
make test
57
63
58
64
7. Commit your changes.
59
65
@@ -63,7 +69,7 @@ Contributing Code
63
69
Running the Test Suite Locally
64
70
------------------------------
65
71
66
-
Configure the following environment variables in your development environment:
72
+
To run the test suite locally, you must configure the following environment variables in your development environment:
67
73
68
74
* ``WEBEX_ACCESS_TOKEN`` - Your test account's Webex access token.
69
75
@@ -83,12 +89,17 @@ Configure the following environment variables in your development environment:
Welcome to the docs! webexpythonsdk is a *community developed* Pythonic wrapping of the Webex APIs. The package represents all of the Cisco Webex API interactions via native Python tools. Making working with the Cisco Webex APIs in Python a *native* and *natural* experience.
11
+
Welcome to the docs! ``webexpythonsdk`` is a *community developed* Pythonic wrapping of the Webex APIs. The package represents all of the Cisco Webex API interactions via native Python tools. Making working with the Cisco Webex APIs in Python a *native* and *natural* experience.
12
12
13
-
**webexpythonsdkhelps you get things done faster.** We take care of the API semantics, and you can focus on writing your code.
13
+
``webexpythonsdk`` **helps you get things done faster.** We take care of the API semantics, and you can focus on writing your code.
14
14
15
-
With webexpythonsdk, you can easily:
15
+
With ``webexpythonsdk``, you can easily:
16
16
17
17
* Interact with the Webex APIs in an interactive Python session
``webexpythonsdk`` is designed to be a drop-in replacement for the ``webexteamssdk`` package. The SDK interface and data objects are largely unchanged with only a few minor name changes.
12
+
13
+
Major changes that you should be aware of:
14
+
15
+
* The package name has changed from ``webexteamssdk`` to ``webexpythonsdk``
16
+
* ``webexpythonsdk`` drops support for Python v2, and supports Python 3.10+
17
+
* The primary API object has changed from ``WebexTeamsAPI`` to ``WebexAPI``
18
+
19
+
20
+
21
+
---------------
22
+
Migration Guide
23
+
---------------
24
+
25
+
TL;DR: Update the package dependency, environment variables, imports, and primary API object.
26
+
27
+
The following table summarizes the name changes that need to be made to migrate from
*Note:* The old ``WEBEX_TEAMS_ACCESS_TOKEN`` environment variable should continue to work with the new package; however, you will receive a deprecation warning. It is recommended to update the environment variable name to ``WEBEX_ACCESS_TOKEN``.
41
+
42
+
**Doing a quick search-and-replace in your codebase should be all you need to do to migrate.**
43
+
44
+
Detailed Steps
45
+
--------------
46
+
47
+
1. Update Package
48
+
49
+
Ensure you update the package in your project's dependencies:
50
+
51
+
.. code-block:: bash
52
+
53
+
pip uninstall webexteamssdk
54
+
pip install webexpythonsdk
55
+
56
+
57
+
2. Update Environment Variables
58
+
59
+
If you are using the ``WEBEX_TEAMS_ACCESS_TOKEN`` environment variable, you will need to update it to ``WEBEX_ACCESS_TOKEN``.
60
+
61
+
3. Codebase Changes
62
+
63
+
**Imports:** Replace all imports from ``webexteamssdk`` to ``webexpythonsdk``.
64
+
65
+
**Primary API Object:** Replace all instances of ``WebexTeamsAPI`` with ``WebexAPI``.
66
+
67
+
----------------
68
+
For Contributors
69
+
----------------
70
+
71
+
Project changes that you should be aware of:
72
+
73
+
- Tooling changes:
74
+
- Using GitHub Actions for CI/CD
75
+
- Using `poetry`_ for packaging and dependency management
76
+
- Using `poetry-dynamic-versioning`_ for version management
77
+
- Using `ruff`_ for linting and code formatting
78
+
- Using `make`_ to automate common tasks
79
+
- The test suite environment variable names have changed:
0 commit comments