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
# Contributing to the Apache Cassandra GoCQL Driver
2
2
3
-
**TL;DR**- this manifesto sets out the bare minimum requirements for submitting a patch to gocql.
3
+
**TL;DR**This manifesto sets out the bare minimum requirements for submitting a patch to gocql. It also offers some suggestions to speed up the review, approve and merge process.
4
4
5
5
This guide outlines the process of landing patches in gocql and the general approach to maintaining the code base.
6
6
7
7
## Background
8
8
9
-
The goal of the gocql project is to provide a stable and robust CQL driver for Go. This is a community driven project that is coordinated by a small team of developers in and around the Apache Cassandra project. For security, governance and administration issues please refer to the Cassandra Project Management Committee.
9
+
The goal of the gocql project is to provide a stable and robust CQL driver for Go. This is a community driven project that is coordinated by a small team of developers in and around the Apache Cassandra project. For security, governance and administration issues please refer to the Cassandra Project Management Committee.
10
+
11
+
## Engage with the community early
12
+
13
+
If you are interested in contributing a particular feature or bug fix we heavily encourage you to start a discussion with the community or at the very least announce your interest in working on it before jumping right into writing code. It helps reduce the likelihood of multiple people working on the same issue in parallel when they could be collaborating instead. Getting feedback early in the contribution process will also greatly speed up the review, approval and merge process.
14
+
15
+
Common ways to engage with the GoCQL community are:
16
+
17
+
-[CASSGO project on ASF JIRA](https://issues.apache.org/jira/projects/CASSGO/issues/)
-[#cassandra-drivers channel on ASF Slack](https://the-asf.slack.com/archives/C05LPRVNZV1)
10
22
11
23
## Minimum Requirement Checklist
12
24
13
25
The following is a check list of requirements that need to be satisfied in order for us to merge your patch:
14
26
15
-
* You should raise a pull request to apache/cassandra-gocql-driver on Github
16
-
* The pull request has a title that clearly summarizes the purpose of the patch
27
+
* A JIRA issue exists in the [CASSGO Project](https://issues.apache.org/jira/projects/CASSGO/issues/) for the proposed changes
28
+
* If the proposed changes are significant then ideally a discussion about the implementation approach should happen before a PR is even opened (prototyping is fine though)
29
+
* Pull request raised to apache/cassandra-gocql-driver on Github
30
+
* The pull request has a title that clearly summarizes the purpose of the patch and references the relevant CASSGO JIRA issue if there is one
17
31
* The motivation behind the patch is clearly defined in the pull request summary
32
+
* JIRA issue is added to the "UNRELEASED" section of CHANGELOG.md
33
+
* If there's no JIRA issue yet then the author is encouraged to create it
34
+
* If the author is not able to create the JIRA issue then the committer that merges the PR will take care of this (creating the JIRA and adding it to CHANGELOG.md)
35
+
* Updating CHANGELOG.md is not required if the change is not "releasable" (e.g. changes to documentation, CI, etc.)
18
36
* You agree that your contribution is donated to the Apache Software Foundation (appropriate copyright is on all new files)
19
37
* The patch will merge cleanly
20
38
* The test coverage does not fall
21
39
* The merge commit passes the regression test suite on GitHub Actions
22
40
*`go fmt` has been applied to the submitted code
23
-
*Notable changes (i.e. new features or changed behavior, bugfixes) are appropriately documented in CHANGELOG.md, functional changes also in godoc
41
+
*Functional changes are documented in godoc
24
42
* A correctly formatted commit message, see below
25
43
26
-
If there are any requirements that can't be reasonably satisfied, please state this either on the pull request or as part of discussion on the mailing list. Where appropriate, the core team may apply discretion and make an exception to these requirements.
44
+
If there are any requirements that can't be reasonably satisfied, please state this either on the pull request or as part of discussion on the mailing list, JIRA or slack. Where appropriate, the core team may apply discretion and make an exception to these requirements.
27
45
28
46
## Commit Message
29
47
30
-
The Apache Cassandra project has a commit message precendence like
48
+
The commit message format should be:
49
+
31
50
```
32
-
<One sentence description, usually Jira title or CHANGES.txt summary>
51
+
<short description>
52
+
53
+
<reason why the change is needed>
33
54
34
-
patch by <Authors>; reviewed by <Reviewers> for CASSANDRA-#####
55
+
Patch by <authors>; reviewed by <Reviewers> for CASSGO-#####
35
56
```
36
57
37
-
The 'patch by …; reviewed by' line is important. It permits our review-than-commit procedure, allowing commits from non-git-branch patches. It is also parsed to build the project contribulyse statistics found [here](https://nightlies.apache.org/cassandra/devbranch/misc/contribulyze/html/).
58
+
Short description should:
59
+
* Be a short sentence.
60
+
* Start with a capital letter.
61
+
* Be written in the present tense.
62
+
* Summarize what is changed, not why it is changed.
38
63
64
+
Short description should not:
65
+
* End with a period.
66
+
* Use the word Fixes . Most commits fix something.
67
+
68
+
Long description / Reason:
69
+
* Should describe why the change is needed. What is fixed by the change? Why it it was broken before? What use case does the new feature solve?
70
+
* Consider adding details of other options that you considered when implementing the change and why you made the design decisions you made.
71
+
72
+
The `patch by …; reviewed by` line is important. It is parsed to build the [project contribulyse statistics](https://nightlies.apache.org/cassandra/devbranch/misc/contribulyze/html/).
73
+
74
+
Some tips from the Apache Cassandra Project's "How to Commit" documentation: https://cassandra.apache.org/_/development/how_to_commit.html#tips
Client timeouts need to be higher than server timeouts,
82
+
so that work does not accumulate on the server with retries.
83
+
If the client timeout is shorter than a server timeout,
84
+
the client can start a retry while the original request
85
+
is still running on the server.
86
+
87
+
The default gocql default timeout was lower
88
+
than the Cassandra default timeout.
89
+
90
+
Cassandra has multiple server timeout options,
91
+
most of them are less or equal to 10s by default as of Cassandra 4.1:
92
+
93
+
read_request_timeout 5s
94
+
range_request_timeout 10s
95
+
write_request_timeout 2s
96
+
counter_write_request_timeout 5s
97
+
cas_contention_timeout 1s
98
+
truncate_request_timeout 60s
99
+
request_timeout 10s
100
+
101
+
Truncate is an uncommon operation, so we can use 11s as the default
102
+
timeout.
103
+
104
+
patch by John Doe, Jane Doe; reviewed by Bob Smith, Jane Smith for CASSGO-#####
105
+
```
106
+
107
+
### Signing commits
108
+
109
+
Signing commits with a pgp or ssh key is heavily encouraged although not required.
41
110
42
111
## Beyond The Checklist
43
112
@@ -55,8 +124,14 @@ That said, the point of writing tests is to provide a safety net to catch regres
55
124
56
125
### Sign Off Procedure
57
126
58
-
Generally speaking, a pull request can get merged by any one of the project's committers. If your change is minor, chances are that one team member will just go ahead and merge it there and then. As stated earlier, suitable test coverage will increase the likelihood that a single reviewer will assess and merge your change. If your change has no test coverage, or looks like it may have wider implications for the health and stability of the library, the reviewer may elect to refer the change to another team member to achieve consensus before proceeding. Therefore, the tighter and cleaner your patch is, the quicker it will go through the review process.
127
+
A Pull Request needs +1s from two committers before it can be merged (or one +1 if the author is a committer).
128
+
129
+
As stated earlier, suitable test coverage will increase the likelihood that a PR will be approved and merged. If your change has no test coverage, or looks like it may have wider implications for the health and stability of the library, the reviewers may elect to refer the change to other members of the community to achieve consensus before proceeding. Therefore, the tighter and cleaner your patch is, the quicker it will go through the review process.
59
130
60
131
### Supported Features
61
132
62
-
gocql is a low level wire driver for Cassandra CQL. By and large, we would like to keep the functional scope of the library as narrow as possible. We think that gocql should be tight and focused, and we will be naturally skeptical of things that could just as easily be implemented in a higher layer. Inevitably you will come across something that could be implemented in a higher layer, save for a minor change to the core API. In this instance, please strike up a conversation in the Cassandra community. Chances are we will understand what you are trying to achieve and will try to accommodate this in a maintainable way.
133
+
gocql is a low level wire driver for Cassandra CQL. By and large, we would like to keep the functional scope of the library as narrow as possible. We think that gocql should be tight and focused, and we will be naturally skeptical of things that could just as easily be implemented in a higher layer.
134
+
135
+
Inevitably you will come across something that could be implemented in a higher layer, save for a minor change to the core API. In this instance, please strike up a conversation in the Cassandra community.
136
+
137
+
Chances are we will understand what you are trying to achieve and will try to accommodate this in a maintainable way.
0 commit comments