1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
## Contributing
This project welcomes contributions and suggestions. Most contributions
require you to agree to a Contributor License Agreement (CLA) declaring that
you have the right to, and actually do, grant us the rights to use your
contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine
whether you need to provide a CLA and decorate the PR appropriately (e.g.,
label, comment). Simply follow the instructions provided by the bot. You
will only need to do this once across all repositories using our CLA.
This project has adopted the [Microsoft Open Source Code of
Conduct](https://opensource.microsoft.com/codeofconduct/). For more
information see the [Code of Conduct
FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact
[opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional
questions or comments.
### Following our coding conventions
We format all our code using the coding conventions in the
[citus_indent](https://github.com/citusdata/tools/tree/develop/uncrustify)
tool. This tool uses uncrustify under the hood. To format the python test files
we use [black](https://github.com/psf/black).
```bash
# Uncrustify changes the way it formats code every release a bit. To make sure
# everyone formats consistently we use version 0.68.1:
curl -L https://github.com/uncrustify/uncrustify/archive/uncrustify-0.68.1.tar.gz | tar xz
cd uncrustify-uncrustify-0.68.1/
mkdir build
cd build
cmake ..
make -j5
sudo make install
cd ../..
git clone https://github.com/citusdata/tools.git
cd tools
make uncrustify/.install
# Be sure to add ~/.local/bin to PATH so you can find black
pip install black --user
```
After installing like this you can run the following before committing:
```bash
make indent
```
You can also run the following to automatically format all the files that you
have changed before committing.
```bash
cat > .git/hooks/pre-commit << __EOF__
#!/bin/bash
citus_indent --check --diff || { citus_indent --diff; exit 1; }
black --check --quiet . || { black .; exit 1; }
__EOF__
chmod +x .git/hooks/pre-commit
```
### Running tests
The integration tests are written using Python and the
[nose](https://nose.readthedocs.io/en/latest/index.html) testing framework.
They are run in a docker container, so you need
[docker](https://docs.docker.com/get-docker/) installed locally.
```bash
make run-test
```
You can filter the tests you are running with the `TEST` environment variable.
```bash
make TEST=multi run-test # runs tests matching tests/test_multi*
make TEST=single run-test # runs tests _not_ matching tests/test_multi*
make TEST=test_auth run-test # runs tests/test_auth.py
```
#### Running tablespace tests
The tablespace tests are similarly written using Python and the nose framework,
with as much shared code as possible. They run using
[docker compose](https://docs.docker.com/compose/), as postgres assumes that
tablespaces live in the same location across replicas. This necessitates
matching directory structures across the nodes, and thus, multiple,
simultaneously running containers.
Interaction with each node is done using `docker compose` commands. Refer to
the [Makefile](tests/tablespaces/Makefile) in the test directory for examples.
To run the tests from the top-level directory:
```bash
TEST=tablespaces make test
```
Like the other tests, you can use `PGVERSION` to test against supported versions
of postgres, for example:
```bash
PGVERSION=14 TEST=tablespaces make test
```
If the tests fail, the docker containers may be left around, and there is a
companion teardown target:
```bash
make -C tests/tablespaces teardown
```
Refer to the [Makefile](tests/tablespaces/Makefile) for more potentially
useful targets to use while developing with tablespaces.
### Producing the documentation diagrams
The diagrams are TikZ sources, which means they're edited with your usual
editor tooling. The diagrams are actually code, and the compilation tool
chain involves the following software:
- LuaTex
- TikZ
- pdftocairo, found in the poppler software
Current TeX distributions should include luatex and tikz for you already.
One such distribution is TexLive and is widely available.
If you want to use TexLive, note that you may need to install some extra
packages for the styles we use in our PDFs. For example `texlive-fonts-extra`
is needed for Debian.
#### For Ubuntu
```
sudo apt-get install latexmk texlive texlive-luatex texlive-latex-extra poppler-utils
```
|
