bschoening commented on code in PR #311: URL: https://github.com/apache/cassandra-website/pull/311#discussion_r3031069931
########## site-content/source/modules/ROOT/pages/development/how_to_commit.adoc: ########## @@ -4,10 +4,35 @@ Commits applicable to multiple versions are atomically pushed forward merges. -The fix lands on the oldest release branch and is then forward-merges it into each newer branch using an ours merge to record branch lineage and amends that merge commit to include the branch-appropriate patch. +Fixes are applied first on the oldest applicable release branch, and are then forward-merged onto each newer branch using an ours merge strategy to record branch lineage. Each forward-merge commit contains the branch-appropriate patch. This keeps a clean, traceable history and a single logical unit of work per ticket per branch, while preventing unintended diffs from being pulled forward automatically. +== Introduction for New Committers + +Patches are applied using git command lines, not via github UI. The following outlines the simple trunk-only patch workflow. See next section for multi-branch contributions. + +Development branches are kept in forks. The upstream apache/cassandra repository is reserved for trunk and release branches. + +Use the following Git CLI commands when merging a PR: + +Step 1: From your project repository, check out a new branch and test the changes. +[source,shell] +---- +git checkout -b <jira>/<branch> <branch> +---- + +Step 2: Squash, fast-forward merge, and update on GitHub following the project workflow. +[source,shell] +---- +git switch trunk +# there should only be one commit, squashed +git cherry-pick <jira>/<branch> +git push --atomic origin trunk -n +# check dry-run looks correct Review Comment: shouldn't the dry run comment (-n) be before the command not after? I realize it's suggesting to check afterwards, but might be be more clear if the dry run was explained before executed. # push as dry-run (-n) and check that it looks correct ########## site-content/source/modules/ROOT/pages/development/how_to_commit.adoc: ########## @@ -4,10 +4,35 @@ Commits applicable to multiple versions are atomically pushed forward merges. -The fix lands on the oldest release branch and is then forward-merges it into each newer branch using an ours merge to record branch lineage and amends that merge commit to include the branch-appropriate patch. +Fixes are applied first on the oldest applicable release branch, and are then forward-merged onto each newer branch using an ours merge strategy to record branch lineage. Each forward-merge commit contains the branch-appropriate patch. This keeps a clean, traceable history and a single logical unit of work per ticket per branch, while preventing unintended diffs from being pulled forward automatically. +== Introduction for New Committers + +Patches are applied using git command lines, not via github UI. The following outlines the simple trunk-only patch workflow. See next section for multi-branch contributions. + +Development branches are kept in forks. The upstream apache/cassandra repository is reserved for trunk and release branches. + +Use the following Git CLI commands when merging a PR: + +Step 1: From your project repository, check out a new branch and test the changes. +[source,shell] +---- +git checkout -b <jira>/<branch> <branch> +---- + +Step 2: Squash, fast-forward merge, and update on GitHub following the project workflow. +[source,shell] +---- +git switch trunk +# there should only be one commit, squashed +git cherry-pick <jira>/<branch> Review Comment: cherry pick a branch or commit-hash? ########## site-content/source/modules/ROOT/pages/development/how_to_commit.adoc: ########## @@ -8,6 +8,36 @@ The fix lands on the oldest release branch and is then forward-merges it into ea This keeps a clean, traceable history and a single logical unit of work per ticket per branch, while preventing unintended diffs from being pulled forward automatically. +== Introduction for New Committers + +To be an effective committer, you should be familiar with the following background details. While this is not a git tutorial, it outlines the expected workflow: + +* **Using CLI vs GitHub web UI:** We recommend using the Git CLI rather than the GitHub web UI. +* **Local feature branches:** Always do your work in a local branch, and never push a branch upstream. +* **Workflow:** This repository uses a squash-rebase-merge workflow with feature branches. +* **Basic git commands you should know:** +** `git remote add` & `git remote set-url` +** Squashing commits with `git rebase -i` +** Updating a commit with `git commit --amend` +** `git push upstream <repo> --atomic -n` + +GitHub offers these CLI commands for merging a PR: Review Comment: Should be git commands, not github ########## site-content/source/modules/ROOT/pages/development/how_to_commit.adoc: ########## @@ -4,10 +4,35 @@ Commits applicable to multiple versions are atomically pushed forward merges. -The fix lands on the oldest release branch and is then forward-merges it into each newer branch using an ours merge to record branch lineage and amends that merge commit to include the branch-appropriate patch. +Fixes are applied first on the oldest applicable release branch, and are then forward-merged onto each newer branch using an ours merge strategy to record branch lineage. Each forward-merge commit contains the branch-appropriate patch. This keeps a clean, traceable history and a single logical unit of work per ticket per branch, while preventing unintended diffs from being pulled forward automatically. +== Introduction for New Committers + +Patches are applied using git command lines, not via github UI. The following outlines the simple trunk-only patch workflow. See next section for multi-branch contributions. + +Development branches are kept in forks. The upstream apache/cassandra repository is reserved for trunk and release branches. Review Comment: Development occurs within personal forks, as the upstream ``apache/cassandra`` repository is strictly reserved for the trunk and official release branches. ########## site-content/source/modules/ROOT/pages/development/how_to_commit.adoc: ########## @@ -8,6 +8,36 @@ The fix lands on the oldest release branch and is then forward-merges it into ea This keeps a clean, traceable history and a single logical unit of work per ticket per branch, while preventing unintended diffs from being pulled forward automatically. +== Introduction for New Committers + +To be an effective committer, you should be familiar with the following background details. While this is not a git tutorial, it outlines the expected workflow: + +* **Using CLI vs GitHub web UI:** We recommend using the Git CLI rather than the GitHub web UI. Review Comment: but why? ########## site-content/source/modules/ROOT/pages/development/how_to_commit.adoc: ########## @@ -8,6 +8,36 @@ The fix lands on the oldest release branch and is then forward-merges it into ea This keeps a clean, traceable history and a single logical unit of work per ticket per branch, while preventing unintended diffs from being pulled forward automatically. +== Introduction for New Committers + +To be an effective committer, you should be familiar with the following background details. While this is not a git tutorial, it outlines the expected workflow: + +* **Using CLI vs GitHub web UI:** We recommend using the Git CLI rather than the GitHub web UI. +* **Local feature branches:** Always do your work in a local branch, and never push a branch upstream. +* **Workflow:** This repository uses a squash-rebase-merge workflow with feature branches. +* **Basic git commands you should know:** +** `git remote add` & `git remote set-url` +** Squashing commits with `git rebase -i` +** Updating a commit with `git commit --amend` +** `git push upstream <repo> --atomic -n` + +GitHub offers these CLI commands for merging a PR: + +Step 1: From your project repository, check out a new branch and test the changes. +[source,shell] +---- +git checkout -b omniCoder77-feature/guardrail-for-misprepare-statements trunk +git pull https://github.com/omniCoder77/cassandra.git feature/guardrail-for-misprepare-statements Review Comment: It's general practice to use branch names with the Jira ID in the name, e.g. CASSANDRA-9999. You can look at some open PRs for examples. ########## site-content/source/modules/ROOT/pages/development/how_to_commit.adoc: ########## @@ -4,10 +4,35 @@ Commits applicable to multiple versions are atomically pushed forward merges. -The fix lands on the oldest release branch and is then forward-merges it into each newer branch using an ours merge to record branch lineage and amends that merge commit to include the branch-appropriate patch. +Fixes are applied first on the oldest applicable release branch, and are then forward-merged onto each newer branch using an ours merge strategy to record branch lineage. Each forward-merge commit contains the branch-appropriate patch. This keeps a clean, traceable history and a single logical unit of work per ticket per branch, while preventing unintended diffs from being pulled forward automatically. +== Introduction for New Committers + +Patches are applied using git command lines, not via github UI. The following outlines the simple trunk-only patch workflow. See next section for multi-branch contributions. Review Comment: Suggest: GitHub Pull Requests are merged using Git command-line tools instead of the GitHub UI. The following workflow outlines a standard trunk-only patching process; for contributions involving multiple branches, see the next section. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
