Skip to content

Improving CONTRIBUTING.md for new contributors (CASSANDRA-20852). #4327

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 1 commit into
base: trunk
Choose a base branch
from
Open

Improving CONTRIBUTING.md for new contributors (CASSANDRA-20852). #4327

wants to merge 1 commit into from

Conversation

jcshepherd
Copy link
Contributor

Initial pass at fleshing out CONTRIBUTING.md to make it more welcoming for new contributors and provide pointers to basic development documentation. Planning on a second pass through website docs to clarify patch guidance from discussion thread: https://lists.apache.org/thread/5718pqmxzn5dwzswrlls75o2gtg1szf3

patch by jcshepherd, reviewed by TBD for https://issues.apache.org/jira/browse/CASSANDRA-20852

Thanks for sending a pull request! Here are some tips if you're new here:

  • Ensure you have added or run the appropriate tests for your PR.
  • Be sure to keep the PR description updated to reflect all changes.
  • Write your PR title to summarize what this PR proposes.
  • If possible, provide a concise example to reproduce the issue for a faster review.
  • Read our contributor guidelines
  • If you're making a documentation change, see our guide to documentation contribution

Commit messages should follow the following format:

<One sentence description, usually Jira title or CHANGES.txt summary>

<Optional lengthier description (context on patch)>

patch by <Authors>; reviewed by <Reviewers> for CASSANDRA-#####

Co-authored-by: Name1 <email1>
Co-authored-by: Name2 <email2>

The Cassandra Jira

Maxwell-Guo
Maxwell-Guo reviewed Aug 21, 2025
View reviewed changes
CONTRIBUTING.md Outdated
Apache Cassandra doesn't use GitHub pull requests as part of the development process.
In fact, this repository is a GitHub mirror of [the official repo](https://gitbox.apache.org/repos/asf/cassandra.git).
There are many opportunities to contribute code to Apache Cassandra, including documentation updates, test improvements,
bug fixes, changes to the Java code base, and tooling improvements (both Python and Java). The basic workflow is the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tooling improvements means ? nodetool or cassandra drivers(python / go/ java) or tools like cassandra-dtest,cassandra-spark-connector or service like cassandra-analytics?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question. When I wrote that, I had things like nodetool and the utilities in the core package's tools/ directory in mind. I could mention, separately, these other ongoing projects as potential areas to contribute but want to respect the fact that they are somewhat separate initiatives from the core project.

CONTRIBUTING.md Outdated
2. Clone the [Apache Cassandra GitHub repo](https://github.com/apache/cassandra).
3. Create your feature branch. Suggestion: name your branch with the related JIRA id: e.g. CASSANDRA-12345 .
4. Make, build, test and self-review your changes on your feature branch.
5. Submit the patch, either by attaching a patch file to your JIRA, creating a GitHub pull request, or posting a
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it seems that ”attaching a patch file to your JIRA“ has not been used for a long time. @michaelsembwever am i right ?

Maxwell-Guo
Maxwell-Guo reviewed Aug 22, 2025
View reviewed changes
CONTRIBUTING.md Outdated
bug fixes, changes to the Java code base, and tooling improvements (both Python and Java). The basic workflow is the
same for all:
1. Find or create an issue in the [Cassandra JIRA](https://issues.apache.org/jira/browse/CASSANDRA/) that describes the work you plan to do.
2. Clone the [Apache Cassandra GitHub repo](https://github.com/apache/cassandra).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think step 2 is to fork your own repo ?

@jcshepherd
Copy link
Contributor Author

Revised per feedback.

michaelsembwever
michaelsembwever reviewed Aug 26, 2025
View reviewed changes
CONTRIBUTING.md Outdated
1. Find or create an issue in the [Cassandra JIRA](https://issues.apache.org/jira/browse/CASSANDRA/) that describes the work you plan to do.
2. Create a personal fork of the [Apache Cassandra GitHub repo](https://github.com/apache/cassandra).
3. Clone your fork into your development environment.
4. Create your feature branch. Suggestion: name your branch with the related JIRA id: e.g. CASSANDRA-12345 .
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
4. Create your feature branch. Suggestion: name your branch with the related JIRA id: e.g. CASSANDRA-12345 .
4. Create your feature branch. Suggestion: name your branch with the related JIRA id: e.g. your-name/CASSANDRA-12345/base-branch .

Copy link
Member

@michaelsembwever michaelsembwever Aug 26, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the reasoning for the your-name/ prefix is it helps teams work together (e.g. when needing to rebase dev branches). it's also nice to see branches in a shared fork sorted first by owner (and makes cleaning up old stale branches easier).

the reasoning for the /base-branch suffix is when patches differ across baselines and need separate branches. we still want these categorised by owner and then ticket.

--

another time, build/sh/development-switch.sh could be improved.

its --jira flag could be renamed to --branch (as it has actually nothing to do with a jira, just the branch name). (e.g. you don't have to first have a jira to create a dev branch)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Mick: please take a look at the latest revision and let me know what you think.

@jcshepherd
Improving CONTRIBUTING.md for new contributors (CASSANDRA-20852).
4b7e95a 
Initial pass at fleshing out CONTRIBUTING.md to make it more welcoming for new contributors and provide
pointers to basic development documentation. Planning on a second pass through website docs to clarify
patch guidance from discussion thread: https://lists.apache.org/thread/5718pqmxzn5dwzswrlls75o2gtg1szf3

patch by jcshepherd, reviewed by Maxwell-Guo,michaelsembwever
@jcshepherd
Copy link
Contributor Author

Commits squashed: thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@michaelsembwever michaelsembwever michaelsembwever approved these changes

@Maxwell-Guo Maxwell-Guo Maxwell-Guo approved these changes

Assignees
No one assigned
Labels
docs
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@jcshepherd @michaelsembwever @Maxwell-Guo @smiklosovic