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/dev-guide.md
+99-48Lines changed: 99 additions & 48 deletions
Original file line number
Diff line number
Diff line change
@@ -3,24 +3,28 @@ title: Developer Guide
3
3
layout: docs
4
4
---
5
5
6
-
This topic describes how to contribute to the Tableau Server Client (Python) project.
6
+
This topic describes how to contribute to the Tableau Server Client (Python)
7
+
project:
7
8
8
-
* TOC
9
+
<!-- prettier-ignore -->
10
+
- TOC
9
11
{:toc}
10
12
11
13
---
12
14
13
15
## Submit your first patch
14
16
15
-
This section will get you started with the basic workflow, describing how to create your own fork of the repository and how to open a pull request (PR) to add your contributions to the **development** branch.
17
+
This section will get you started with the basic workflow, describing how to
18
+
create your own fork of the repository and how to open a pull request (PR) to
19
+
add your contributions to the **development** branch.
16
20
17
21
### Get the source code and set up your branch
18
22
19
-
1. Make sure you have [signed the CLA](https://tableau.github.io/contributing.html)
23
+
1. Make sure you have
24
+
[signed the CLA](https://tableau.github.io/contributing.html).
20
25
21
-
1. Fork the repository.
22
-
23
-
We follow the "Fork and Pull" model as described [here](https://help.github.com/articles/about-collaborative-development-models/).
26
+
1. Fork the repository. We follow the "Fork and Pull" model as described
@@ -34,72 +38,119 @@ This section will get you started with the basic workflow, describing how to cre
34
38
python setup.py test
35
39
```
36
40
37
-
1. Set up the feature, fix, or documentation branch.
38
-
39
-
It is recommended to use the format issue#-type-description (e.g. 13-fix-connection-bug) like so:
41
+
1. Set up the feature/fix branch (based off the `development` branch). It is
42
+
recommended to use the format issue#-type-description, for example:
40
43
41
44
```shell
42
-
git checkout -b 13-feature-new-stuff development
45
+
git checkout -b 13-fix-connection-bug development
43
46
```
44
47
45
-
For documentation changes, see the documentation section below.
48
+
For documentation changes, see the documentation section below.
46
49
47
50
### Code and commit
48
51
49
-
Here's a quick checklist to follow when coding to ensure a good pull request (PR):
52
+
Here's a quick checklist to follow when coding to ensure a good pull request
53
+
(PR):
54
+
55
+
- Only touch the fewest number of files possible while still accomplishing the
56
+
goal.
57
+
- Ensure all indentation is done as 4-spaces and your editor is set to unix line
58
+
endings.
59
+
- The code matches PEP8 style guides. Make sure to run
60
+
`pycodestyle tableauserverclient test samples` to catch and fix any style
61
+
issues before submitting your pull request.
62
+
- Keep commit messages clean and descriptive.
63
+
64
+
### Adding features
65
+
66
+
1. Create an endpoint class for the new feature, following the structure of the
67
+
other endpoints. Each endpoint usually has `get`, `post`, `update`, and
68
+
`delete` operations that require making the url, creating the XML request if
69
+
necessary, sending the request, and creating the target item object based on
70
+
the server response.
71
+
72
+
1. Create an item class for the new feature, following the structure of the
73
+
other item classes. Each item has properties that correspond to what
74
+
attributes are sent to/received from the server (refer to docs and Postman
75
+
for attributes). Some items also require constants for user input that are
76
+
limited to specific strings. After making all the properties, make the
77
+
parsing method that takes the server response and creates an instances of the
78
+
target item. If the corresponding endpoint class has an update function, then
79
+
parsing is broken into multiple parts (refer to another item like workbook or
80
+
datasource for example).
81
+
82
+
1. Add testing by getting real xml responses from the server, and asserting that
83
+
all properties are parsed and set correctly.
50
84
51
-
- Only touch the fewest number of files possible while still accomplishing the goal.
52
-
- Ensure all indentation is done as 4-spaces and your editor is set to unix line endings.
53
-
- The code matches PEP8 style guides. If you cloned the repo you can run `pycodestyle tableauserverclient test samples`
54
-
- Keep commit messages clean and descriptive.
55
-
If the PR is accepted it will get 'Squashed' into a single commit before merging, the commit messages will be used to generate the Merge commit message.
85
+
1. Add a sample to show users how to use the new feature.
56
86
57
87
### Add tests
58
88
59
-
All of our tests live under the `test/` folder in the repository.
60
-
We use `pytest` and the built-in test runner `python setup.py test`.
61
-
If a test needs a static file, like a .twb/.twbx, it should live under `test/assets/`
89
+
All of our tests live under the `test/` folder in the repository. We use
90
+
`pytest` and the built-in test runner `python setup.py test`.
91
+
92
+
Follow the structure of existing tests, especially if new server responses
93
+
are going to be mocked.
94
+
95
+
If a test needs a
96
+
static file, like a .twb/.twbx/.xml, it should live under `test/assets/`
97
+
98
+
Make sure that all tests are passing before submitting your pull request.
62
99
63
100
### Update the documentation
64
101
65
-
When adding a new feature or improving existing functionality we may ask that you update the documentation along with your code.
102
+
When adding a new feature or improving existing functionality we ask that you
103
+
update the documentation along with your code. See the Updating documentation
104
+
section below for details.
66
105
67
-
Our documentation is written in markdown and built with Jekyll on GitHub Pages. All of the documentation source files can be found in `/docs` folder in the **gh-pages** branch. The docs are hosted on the following URL: [https://tableau.github.io/server-client-python](https://tableau.github.io/server-client-python)
106
+
### Commit changes to your fork and open a pull request
68
107
69
-
If you are just making documentation updates (adding new docs, fixing typos, improving wording) the easiest method is to use the built-in `Edit this file` feature right in GitHub (click the pencil icon). If you are viewing one of the pages on [https://tableau.github.io/server-client-python](https://tableau.github.io/server-client-python), clicking the **Edit this page** link at the top of the page will take you to the same place.
against the **development** branch for code changes.
70
111
71
-
### Commit changes to your fork and open a PR
112
+
1. Wait for a review and address any feedback. While we try and stay on top of
113
+
all issues and PRs it might take a few days for someone to respond. Politely
114
+
pinging the PR after a few days with no response is OK, we'll try and respond
115
+
with a timeline as soon as we are able.
72
116
73
-
1. Make a PR as described [here](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork) against the **development** branch for code changes, or against **gh-pages** for documentation updates.
width="5%"} (:rocket:'s) from members of the core team they will merge the
120
+
PR.
74
121
75
-
1. Wait for a review and address any feedback.
76
-
While we try and stay on top of all issues and PRs it might take a few days for someone to respond. Politely pinging
77
-
the PR after a few days with no response is OK, we'll try and respond with a timeline as soon as we are able.
122
+
## Updating documentation
78
123
79
-
1. That's it! When the PR has received {:height="5%" width="5%"} (:rocket:'s) from members of the core team they will merge the PR.
124
+
Our documentation is written in Markdown (specifically
125
+
[kramdown](https://kramdown.gettalong.org/quickref.html)) and built with Jekyll
126
+
on GitHub Pages.
80
127
81
-
---
128
+
All of the documentation source files can be found in `/docs` folder in the
129
+
**gh-pages** branch. The docs are hosted on the following URL:
130
+
<https://tableau.github.io/server-client-python>.
82
131
83
-
## Add new features
132
+
If you are just making documentation updates (adding new docs, fixing typos,
133
+
improving wording) the easiest method is to use the built-in `Edit this file`
134
+
feature (the pencil icon) or the `Edit this page` link.
84
135
85
-
1. Create an endpoint class for the new feature, following the structure of the other endpoints. Each endpoint usually
86
-
has `get`, `post`, `update`, and `delete` operations that require making the url, creating the XML request if necessary,
87
-
sending the request, and creating the target item object based on the server response.
136
+
To make more significant changes or additions, please create a pull request
137
+
against the **gh-pages** branch. When submitted along with a code pull request
138
+
(as described above), you can include a link in the PR text so it's clear they
139
+
go together.
88
140
89
-
1. Create an item class for the new feature, following the structure of the other item classes. Each item has properties
90
-
that correspond to what attributes are sent to/received from the server (refer to docs and Postman for attributes).
91
-
Some items also require constants for user input that are limited to specific strings. After making all the
92
-
properties, make the parsing method that takes the server response and creates an instances of the target item. If
93
-
the corresponding endpoint class has an update function, then parsing is broken into multiple parts (refer to another
94
-
item like workbook or datasource for example).
141
+
### Running docs locally
95
142
96
-
1. Add testing by getting real xml responses from the server, and asserting that all properties are parsed and set
97
-
correctly.
143
+
To preview and run the documentation locally, these are the steps:
98
144
99
-
1. Add a sample to show users how to use the new feature.
145
+
1. Install [Ruby](https://www.ruby-lang.org/en/downloads/) (v2.5.0 or higher)
0 commit comments