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
Welcome to Pigsty! We're excited that you're interested in contributing.
4
4
5
5
Pigsty is an open-source, cloud-neutral, local-first PostgreSQL distribution that delivers production-ready database clusters.
6
-
Your contributions help make PostgreSQL more accessible and powerful for everyone.
7
-
8
-
## Getting Started
9
-
10
-
Pigsty uses a 4-node sandbox environment based on EL9 (Rocky Linux 9) as the default testing environment.
11
-
You can set up this environment using either **Vagrant** or **Terraform**.
12
-
13
-
```bash
14
-
cd~/pigsty
15
-
make full9
16
-
./configure -c ha/full
17
-
./deploy.yml
18
-
```
19
-
20
-
Check https://pigsty.io/docs/setup/ for details.
6
+
Your feedback and ideas help make PostgreSQL more accessible and powerful for everyone.
21
7
22
8
23
9
## Ways to Contribute
24
10
25
-
There are many ways to contribute to Pigsty, regardless of your experience level:
26
-
27
-
### Report Bugs & Request Features
11
+
### Report Bugs
28
12
29
13
- Search [existing issues](https://github.com/pgsty/pigsty/issues) first to avoid duplicates
30
-
- Use the issue templates when available
31
-
- Provide detailed reproduction steps for bugs
14
+
- Provide detailed reproduction steps
32
15
- Include your Pigsty version, OS version, and relevant configuration
16
+
- Attach logs and error messages when applicable
33
17
34
-
### Improve Documentation
18
+
### Request Features
35
19
36
-
-Fix typos, clarify explanations, or add examples
37
-
-Documentation issues should be submitted to [pgsty/pigsty.io](https://github.com/pgsty/pigsty.io/issues) (EN) / [pgsty/pigsty.cc](https://github.com/pgsty/pigsty.cc/issues) (ZH)
38
-
-Translations are welcome
20
+
-Describe your use case and why the feature would be valuable
21
+
-Explain your current workaround (if any)
22
+
-Be specific about expected behavior
39
23
40
-
### Design Config Templates
24
+
### Suggest Extensions
41
25
42
-
If your scenario isn't covered by existing config templates, consider creating a new one.
43
-
Templates are located in the `conf/` directory:
26
+
Pigsty supports 400+ PostgreSQL extensions. If you need an extension that's not included:
44
27
45
-
```
46
-
conf/
47
-
├── meta.yml # Default 1-node template
48
-
├── rich.yml # Feature-rich with minio & examples
49
-
├── slim.yml # Minimal installation
50
-
├── citus.yml # Distributed PostgreSQL
51
-
├── supabase.yml # Supabase self-hosting
52
-
├── ha/
53
-
│ ├── dual.yml # 2-node HA
54
-
│ ├── trio.yml # 3-node HA
55
-
│ ├── full.yml # 4-node sandbox
56
-
│ └── safe.yml # Security enhanced
57
-
└── ...
58
-
```
28
+
- Open an issue describing the extension and your use case
29
+
- Include links to the extension's repository/documentation
30
+
- Specify which PostgreSQL versions you need it for
59
31
60
-
You can create templates for specific use cases: exotic kernels, special hardware, cloud providers, or industry scenarios.
32
+
### Propose Config Templates
61
33
62
-
### Add Docker App Templates
34
+
If your scenario isn't covered by existing templates in the `conf/` directory, we'd love to hear about it:
63
35
64
-
The `app/` directory contains Docker Compose templates for applications that work well with PostgreSQL.
65
-
You can contribute new templates for popular software:
- Special requirements (compliance, performance, HA topology)
39
+
40
+
Good suggestions may be incorporated into future releases.
41
+
42
+
### Suggest Docker App Templates
43
+
44
+
The `app/` directory contains Docker Compose templates for applications that work well with PostgreSQL:
66
45
67
46
```
68
47
app/
@@ -75,127 +54,65 @@ app/
75
54
└── ...
76
55
```
77
56
78
-
To add a new app template:
79
-
1. Create a new directory under `app/`
80
-
2. Add a `docker-compose.yml` and `README.md`
81
-
3. Ensure it integrates well with Pigsty's PostgreSQL clusters
82
-
4. Submit a pull request
83
-
84
-
### Contribute Grafana Dashboards
85
-
86
-
Dashboards are located in `files/grafana/` with subdirectories for each module (pgsql, node, infra, redis, etc.).
87
-
88
-
To develop and test dashboards:
89
-
90
-
```bash
91
-
export GRAFANA_ENDPOINT=http://10.10.10.10:3000/ui # your grafana endpoint
92
-
make di # dashboard-init: load dashboards to grafana
93
-
make dd # dashboard-dump: dump dashboards from grafana
94
-
```
95
-
96
-
Edit dashboards in Grafana UI, then use `make dd` to export changes back to JSON files.
97
-
98
-
### Contribute Roles & Playbooks
99
-
100
-
If you believe a new Ansible role or playbook would benefit other users, consider contributing it.
101
-
Roles are located in the `roles/` directory:
102
-
103
-
```
104
-
roles/
105
-
├── pgsql/ # PostgreSQL cluster provisioning
106
-
├── node/ # Host provisioning and tuning
107
-
├── infra/ # Monitoring infrastructure
108
-
├── etcd/ # DCS for HA consensus
109
-
├── redis/ # Redis cluster deployment
110
-
├── minio/ # S3-compatible object storage
111
-
└── ...
112
-
```
113
-
114
-
New modules should follow existing patterns and include proper documentation.
115
-
116
-
### Contribute Code
57
+
If you have ideas for new app templates, please open an issue with:
117
58
118
-
-Bug fixes and feature implementations are welcome
119
-
-Follow the existing code style and conventions
120
-
-Test your changes thoroughly before submitting
121
-
-Keep changes focused and atomic
59
+
-The application name and what it does
60
+
-Why it pairs well with PostgreSQL
61
+
-Any specific configuration considerations
62
+
-Links to official documentation
122
63
123
-
### Supported Platforms
64
+
### Suggest Grafana Dashboards
124
65
125
-
When contributing code, please ensure compatibility with:
66
+
Dashboards are located in `files/grafana/` with subdirectories for each module (pgsql, node, infra, redis, etc.).
126
67
127
-
-**OS**: Ubuntu 22/24, Debian 12/13, EL 9/10
128
-
-**Arch**: Linux x86_64, ARM64
129
-
-**PostgreSQL**: 14, 15, 16, 17, 18
130
-
-**Ansible**: 2.9 - 2.19+
68
+
If you have ideas for new dashboards or improvements to existing ones, please describe them in an issue.
131
69
70
+
### Improve Documentation
132
71
72
+
- Report documentation issues to [pgsty/pigsty.io](https://github.com/pgsty/pigsty.io/issues) (EN) or [pgsty/pigsty.cc](https://github.com/pgsty/pigsty.cc/issues) (ZH)
73
+
- Suggest clarifications, point out outdated content, or propose examples
74
+
- Translation suggestions are appreciated
133
75
134
-
## Communication Guidelines
135
76
136
-
###Before Submitting Issues
77
+
## Before Submitting
137
78
138
79
1. Check the [FAQ](https://pigsty.io/docs/setup/faq) and [documentation](https://pigsty.io/docs)
139
80
2. Search [existing issues](https://github.com/pgsty/pigsty/issues) and [discussions](https://github.com/orgs/pgsty/discussions)
140
-
3. Provide sufficient information (see [community help guide](https://github.com/pgsty/pigsty/discussions/338))
81
+
3. Provide sufficient context (see [community help guide](https://github.com/pgsty/pigsty/discussions/338))
141
82
142
-
### For Significant Changes
83
+
For code changes or significant contributions, please open an issue first to discuss.
84
+
This helps ensure alignment with the project's direction and avoids duplicated effort.
143
85
144
-
If you're planning significant modifications to the system, please discuss first in [GitHub Discussions](https://github.com/orgs/pgsty/discussions)
145
-
before investing significant effort. This helps ensure your contribution aligns with the project's direction.
146
86
147
-
###Related Repositories
87
+
## Related Repositories
148
88
149
-
Different types of issues should be submitted to the appropriate repository:
0 commit comments