<commit_before>////
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
////
= For Committers

image::business-gremlin.png[width=400]

The guidelines that follow generally apply to those with commit access to the main repository, but those seeking to
contribute will also find helpful information here on the development style and process for the project.

[[initial-setup]]
== Initial Setup

Once the Apache TinkerPop PMC has sent an invitation to a contributor to become a new committer and that contributor
has accepted that invitation and provided their iCLA to Apache, then there are some administrative steps that the
new committer can expect to go through to complete the process so that they have access to Apache resources like the
Git repository. While the information for completing the process can be found in a multitude of places the following
listing provides a summary of what to do next:

* Look for a welcome email from root_at_apache.org. This will contain your Apache user name
** e.g. "Welcome to the Apache Software Foundation (ASF)!"
* Visit https://id.apache.org/reset/enter and enter your user name
* Look for a password reset email from root_at_apache.org. This will have been sent after you confirmed your user name, above.
** e.g. "Password reset request for [username] from Apache ID"
* Visit the link provided in the password reset email, and choose a new password. ASF asks you to choose a strong one. You will see a "Password change successful" page when this is done.
* You will now have SVN access
** link:https://svn.apache.org/[svn.apache.org]
* Try sending yourself an email at your new [username]<EMAIL> email address. It should forward to your primary address.
* Check your account details at https://id.apache.org/details/[username]
* Link your accounts using gitbox (https://gitbox.apache.org/setup/)
** Link your Apache account
** Link your GitHub account
*** You will be asked to "Authorize Apache M.A.T.T."
** Obtain MFA status
*** Visit link:https://id.apache.org[id.apache.org] and set your GitHub ID to be invited to the org
*** Wait for an email to arrive from "support_at_github.com", and click "Join @apache". Accept the invitation on github.com. Your new MFA status will not immediately be reflected on github, but you will get a confirmation email from noreply_at_github.com. Later, the status will read "MFA ENABLED"
**** e.g. "[GitHub] @asf-gitbox has invited you to join the @apache organization"
*** You can find yourself by searching in the link:https://github.com/orgs/apache/teams/apache-committers[Apache Committers listing]
* Read the link:https://www.apache.org/dev/new-committers-guide.html[Apache Committer Guide] and link:http://www.apache.org/dev/committers.html[Apache Committer FAQ]
* Read through the other sections of this document - the Developer Documentation - for more details on project procedures and other administrative items.
** In particular, see <<rtc,Review then Commit>>
* If you have trouble committing, email <EMAIL>

== Communication

TinkerPop has a link:http://groups.google.com/group/gremlin-users[user mailing list] and a
pass:[<a href="https://lists.apache.org/list.html?<EMAIL>">dev mailing list</a>].  As a committer,
it is a good idea to join both.

TinkerPop also has a link:https://the-asf.slack.com/archives/CUBJ577EW[Slack channel] for more real-time communication
about the project among contributors, though it must be kept in mind that project discussion and decisions must occur
on the dev mailing list mentioned above.

Occasionally, online meetings via video conference are held. These meetings are schedule via the dev mailing list
about a week before they are to occur to find a day and time that is available for those interested in attending.
On the day of the meeting, the meeting organizer will create a Google Hangout (or similar video conferencing link).
At that point, all who are interested can attend.  Meeting minutes should be
taken and added to the <<meetings,Meetings>> section of this document using the pattern already established.

== Release Notes

There is a two-pronged approach to maintaining the change log and preparing the release notes.

1. For work that is documented in JIRA, run the release notes report to include all of
the tickets targeted for a specific release.  This report can be included in the
release announcement.

2. The manual change log (`CHANGELOG.asciidoc`) can be used to highlight large
changes, describe themes (e.g. "We focused on performance improvements") or to
give voice to undocumented changes.

Given the dependence on the JIRA report for generating additions to the `CHANGELOG.asciidoc`,
which uses the title of the issue as the line presented in the release note report, titles should
be edited prior to release to be useful in that context.  In other words, an issue title should
be understandable as a change in the fewest words possible while still conveying the gist of the
change.

Changes that break the public APIs should be marked with a "breaking" label and should be
distinguished from other changes in the release notes.

[[branches]]
== Branches

TinkerPop has several release branches:

* `3.0-dev` - 3.0.x (no longer maintained)
* `3.1-dev` - 3.1.x (no longer maintained)
* `3.2-dev` - 3.2.x (no longer maintained)
* `3.3-dev` - 3.3.x (no longer maintained)
* `3.4-dev` - 3.4.x (non-breaking bug fixes and enhancements)
* `3.5-dev` - 3.5.x (non-breaking bug fixes and enhancements)
* `master` - 3.6.x (current development)
* `4.0-dev` - 4.0.x (future development)

The branch description above that reads "non-breaking bug fixes and enhancements" simply means that within that release
line (i.e. patch version) changes should not alter existing behavior, introduce new APIs, change serialization formats,
modify protocols, etc. In this way, users and providers have an easy way to know that within a minor release line, they
can be assured that their upgrades will not introduce potential problems. A good rule of thumb is to consider whether a
client of one version within a release line can interact properly with a server version within that same line. If so,
it is likely an acceptable change within that branch.

Changes to earlier branches should merge forward toward `master` (e.g. `3.5-dev` should merge to `master`). Please read
more about this process in the <<pull-requests, Pull Requests>> section. Note that `4.0-dev` is rebased on `master`
and currently behaves as a fresh repository as all 3.x content was removed.

As described in <<versioning,versioning>>, it is possible to do a "partial" release which will utilize a four-digit
version that starts with a "1" (e.g. `3.6.0.1`). The branching strategy for a partial release requires that a `-dev`
branch be created with the three digit prefix.

Other branches may be created for collaborating on features or for RFC's that other developers may want to inspect.
It is suggested that the JIRA issue ID be used as the prefix, since that triggers certain automation, and it provides a
way to account for the branch lifecycle, i.e. "Who's branch is this, and can I delete it?"

For branches that are NOT associated with JIRA issues, developers should utilize their Apache ID as
a branch name prefix.  This provides a unique namespace, and also a way to account for the branch lifecycle.

Developers should remove their own branches when they are no longer needed.

== Tags

Tags are used for milestones, release candidates, and approved <<versioning,partial and complete releases>>. Tags for a
complete release are simply defined by the three-digit version number. Tags for a partial release, should be prefixed
by the individual language relevant to that release. For example, if there is an initial partial release for `3.6.0`
on `gremlin-python` then the tag should be `3.6.0.1-python`.<commit_msg>Update docs to reflect latest branching structure CTR<commit_after>////
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
////
= For Committers

image::business-gremlin.png[width=400]

The guidelines that follow generally apply to those with commit access to the main repository, but those seeking to
contribute will also find helpful information here on the development style and process for the project.

[[initial-setup]]
== Initial Setup

Once the Apache TinkerPop PMC has sent an invitation to a contributor to become a new committer and that contributor
has accepted that invitation and provided their iCLA to Apache, then there are some administrative steps that the
new committer can expect to go through to complete the process so that they have access to Apache resources like the
Git repository. While the information for completing the process can be found in a multitude of places the following
listing provides a summary of what to do next:

* Look for a welcome email from root_at_apache.org. This will contain your Apache user name
** e.g. "Welcome to the Apache Software Foundation (ASF)!"
* Visit https://id.apache.org/reset/enter and enter your user name
* Look for a password reset email from root_at_apache.org. This will have been sent after you confirmed your user name, above.
** e.g. "Password reset request for [username] from Apache ID"
* Visit the link provided in the password reset email, and choose a new password. ASF asks you to choose a strong one. You will see a "Password change successful" page when this is done.
* You will now have SVN access
** link:https://svn.apache.org/[svn.apache.org]
* Try sending yourself an email at your new [username]<EMAIL> email address. It should forward to your primary address.
* Check your account details at https://id.apache.org/details/[username]
* Link your accounts using gitbox (https://gitbox.apache.org/setup/)
** Link your Apache account
** Link your GitHub account
*** You will be asked to "Authorize Apache M.A.T.T."
** Obtain MFA status
*** Visit link:https://id.apache.org[id.apache.org] and set your GitHub ID to be invited to the org
*** Wait for an email to arrive from "support_at_github.com", and click "Join @apache". Accept the invitation on github.com. Your new MFA status will not immediately be reflected on github, but you will get a confirmation email from noreply_at_github.com. Later, the status will read "MFA ENABLED"
**** e.g. "[GitHub] @asf-gitbox has invited you to join the @apache organization"
*** You can find yourself by searching in the link:https://github.com/orgs/apache/teams/apache-committers[Apache Committers listing]
* Read the link:https://www.apache.org/dev/new-committers-guide.html[Apache Committer Guide] and link:http://www.apache.org/dev/committers.html[Apache Committer FAQ]
* Read through the other sections of this document - the Developer Documentation - for more details on project procedures and other administrative items.
** In particular, see <<rtc,Review then Commit>>
* If you have trouble committing, email <EMAIL>

== Communication

TinkerPop has a link:http://groups.google.com/group/gremlin-users[user mailing list] and a
pass:[<a href="https://lists.apache.org/list.html?<EMAIL>">dev mailing list</a>].  As a committer,
it is a good idea to join both.

TinkerPop also has a link:https://the-asf.slack.com/archives/CUBJ577EW[Slack channel] for more real-time communication
about the project among contributors, though it must be kept in mind that project discussion and decisions must occur
on the dev mailing list mentioned above.

Occasionally, online meetings via video conference are held. These meetings are schedule via the dev mailing list
about a week before they are to occur to find a day and time that is available for those interested in attending.
On the day of the meeting, the meeting organizer will create a Google Hangout (or similar video conferencing link).
At that point, all who are interested can attend.  Meeting minutes should be
taken and added to the <<meetings,Meetings>> section of this document using the pattern already established.

== Release Notes

There is a two-pronged approach to maintaining the change log and preparing the release notes.

1. For work that is documented in JIRA, run the release notes report to include all of
the tickets targeted for a specific release.  This report can be included in the
release announcement.

2. The manual change log (`CHANGELOG.asciidoc`) can be used to highlight large
changes, describe themes (e.g. "We focused on performance improvements") or to
give voice to undocumented changes.

Given the dependence on the JIRA report for generating additions to the `CHANGELOG.asciidoc`,
which uses the title of the issue as the line presented in the release note report, titles should
be edited prior to release to be useful in that context.  In other words, an issue title should
be understandable as a change in the fewest words possible while still conveying the gist of the
change.

Changes that break the public APIs should be marked with a "breaking" label and should be
distinguished from other changes in the release notes.

[[branches]]
== Branches

TinkerPop has several release branches:

* `3.0-dev` - 3.0.x (no longer maintained)
* `3.1-dev` - 3.1.x (no longer maintained)
* `3.2-dev` - 3.2.x (no longer maintained)
* `3.3-dev` - 3.3.x (no longer maintained)
* `3.4-dev` - 3.4.x (no longer maintained)
* `3.5-dev` - 3.5.x (non-breaking bug fixes and enhancements)
* `3.6-dev` - 3.6.x (non-breaking bug fixes and enhancements)
* `master` - 3.7.x (current development)
* `4.0-dev` - 4.0.x (future development)

The branch description above that reads "non-breaking bug fixes and enhancements" simply means that within that release
line (i.e. patch version) changes should not alter existing behavior, introduce new APIs, change serialization formats,
modify protocols, etc. In this way, users and providers have an easy way to know that within a minor release line, they
can be assured that their upgrades will not introduce potential problems. A good rule of thumb is to consider whether a
client of one version within a release line can interact properly with a server version within that same line. If so,
it is likely an acceptable change within that branch.

Changes to earlier branches should merge forward toward `master` (e.g. `3.6-dev` should merge to `master`). Please read
more about this process in the <<pull-requests, Pull Requests>> section. Note that `4.0-dev` is rebased on `master`
and currently behaves as a fresh repository as all 3.x content was removed.

As described in <<versioning,versioning>>, it is possible to do a "partial" release which will utilize a four-digit
version that starts with a "1" (e.g. `3.6.0.1`). The branching strategy for a partial release requires that a `-dev`
branch be created with the three digit prefix.

Other branches may be created for collaborating on features or for RFC's that other developers may want to inspect.
It is suggested that the JIRA issue ID be used as the prefix, since that triggers certain automation, and it provides a
way to account for the branch lifecycle, i.e. "Who's branch is this, and can I delete it?"

For branches that are NOT associated with JIRA issues, developers should utilize their Apache ID as
a branch name prefix.  This provides a unique namespace, and also a way to account for the branch lifecycle.

Developers should remove their own branches when they are no longer needed.

== Tags

Tags are used for milestones, release candidates, and approved <<versioning,partial and complete releases>>. Tags for a
complete release are simply defined by the three-digit version number. Tags for a partial release, should be prefixed
by the individual language relevant to that release. For example, if there is an initial partial release for `3.6.0`
on `gremlin-python` then the tag should be `3.6.0.1-python`.
{'fraction_non_alphanumeric': 0.06573043528931881, 'fraction_numerical': 0.007109142823844765, 'mean_word_length': 4.451715374841169, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 33, 'https://': 18, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4930814', 'n_tokens_mistral': 4500, 'n_tokens_neox': 4341, 'n_words': 2489}