SOLR-16746: Migrate How to Contribute Content from cwiki (#1561)

Migrate https://cwiki.apache.org/confluence/display/SOLR/HowToContribute and https://cwiki.apache.org/confluence/display/SOLR/Git+commit+process into our git managed documentation. --------- Co-authored-by: Houston Putman <[email protected]>
apache · Apr 14, 2023 · 6229636 · 6229636
1 parent 67be5d0
commit 6229636
Show file tree

Hide file tree

Showing 7 changed files with 371 additions and 33 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -21,7 +21,8 @@ Thank you for your interest in contributing to the Apache Solr project. Solr con
 
 Your suggestions and comments can be made directly through the [Apache Solr JIRA](https://issues.apache.org/jira/projects/SOLR/issues).
 
-There are many ways to participate in and contribute to Solr, such as: code implementation, test implementation, documentation improvements.
+There are many ways to participate in and contribute to Solr, such as: code implementation, test implementation, documentation improvements.  Participating in the user mailing list, being active on [Solr Slack](https://s.apache.org/solr-slack) answering questions and providing feedback to developers are also powerful ways to contribute to Solr.
+The community is also always looking for [moderators](#be-a-mailing-list-moderator) for the mailing lists.
 
 If you have any questions along the way, you can reach out to the community using the resources provided [here](https://solr.apache.org/community.html#mailing-lists-chat).
 
@@ -53,6 +54,12 @@ Information on JVMs can be found in the [JVMs developer documentation](dev-docs/
 
 Frequently asked questions can be found in the [FAQ developer documentation](dev-docs/FAQ.adoc)
 
-## Additional information
 
-Even more hits and tips are to be found in the [Solr Wiki](https://cwiki.apache.org/confluence/display/solr/HowToContribute). 
+## Be A Mailing List Moderator
+
+Being a list moderator is incredibly easy - the basic responsibilities are:
+
+Get a copy of any email sent to one of the Solr lists from an address that is not subscribed and review it to see if it's spam or not.
+Occasionally help people with particular difficulties unsubscribing to the mailing list.
+
+If you'd like to volunteer to be the moderator of a mailing list, just contact [email protected]... (ie: [email protected]...)
diff --git a/dev-docs/FAQ.adoc b/dev-docs/FAQ.adoc
@@ -72,3 +72,22 @@ Run via:
 `./gradlew owasp`
 
 There are a number of other tasks that get run to validate the source code, and you can find them in the ./gradle/validation source tree.
+
+=== Generated files
+
+There are several files that are generated, for instance several of the tokenizers implement a scanner that is defined in a ".jflex" file.
+It is rarely necessary to modify the ".jflex" file and almost always a mistake to hand-edit the ".java" file generated from it.
+If you see any message at the top of a file you're working with like "/* The following code was generated by JFlex 1.7.0 */" please discuss why you want to change it on the development list before proceeding.
+
+=== JIRA tips (our issue/bug tracker)
+
+The issue tracker we use is a JIRA instance at https://issues.apache.org/jira/browse/SOLR.
+If you don't yet have an account, you have to ask for one in the 'users' or 'dev' mailing list (see https://solr.apache.org/community.html#mailing-lists-chat).
+
+1. If you aren't sure if something is a bug, please ask on the [email protected] mailing list before opening an issue.
+1. We do not use JIRA for support or asking questions. If you have a question, please use the users mailing list.
+1. When creating new issues in JIRA, please keep the "Description" field short - every change or followup on the issue will cause an email to be sent to the [email protected] mailing list, and will include the complete Description every time.
+1. When attaching newer versions of a file/patch, use the same name... JIRA will "gray out" the older versions automatically.
+1. Please do not delete older files that you have already added - the complete history of an issue is important.
+1. The "Activity" section of an issue by default only lists "Comments". If you click on the "All" sub-tab you can see all activity related to this issue, including any edits that might have been made to the summary or description, as well as an commits that mention this issue in the commit log.
+1. Have follow up work to an existing issue that is closed?  If an issue is closed, its supposed to remain closed since it has been "shipped" in a release. Create a new issue and link it.
diff --git a/dev-docs/IDEs.adoc b/dev-docs/IDEs.adoc
@@ -1,10 +1,14 @@
 # IDEs
 
+Both Intellij and Eclipse are supported out of the box.
+
+For Solr 9x and later, executing "gradlew tasks" will list a section "IDE tasks" to get you started.
+The dev mailing list or the slack solr-dev channel are good places for detailed questions.
+
 ## IntelliJ IDEA
 
 Importing the project as a gradle project should just run out of the box.
 
-
 ## Eclipse
 
 Run the following to set up Eclipse project files:
@@ -17,4 +21,4 @@ File -> Import... -> Existing Project into Workspace
 
 Please note that Eclipse does not distinguish between sub-projects
 and package sets (main/ test) so pretty much all the sources and dependencies
-are available in one large bin.
+are available in one large bin.
diff --git a/dev-docs/git.adoc b/dev-docs/git.adoc
@@ -0,0 +1,233 @@
+= Using Git
+
+
+== Committing changes to Git
+
+*Totally incomplete, but we have to start somewhere. Please contribute!*
+
+There's been a lot of discussion about how to commit to the Git repo since we moved to using Git in early 2016. This page is intended for people new to Git or Solr as a place to start. If you're totally new to Git or if you're a new committer, this should get you started.
+
+NOTES:
+
+* Only committers have the ability to commit to the official Git repository.
+* IntelliJ and Eclipse have built-in Git integration
+* There are visual tools that may be used as well. Mention here is not an endorsement, nor is it a complete list.
+ * SourceTree Free.
+ * SmartGit Licensed, not free. Well liked by at least some committers.
+
+== Useful Links
+
+There are about a zillion "how to use Git" links out there, here are a few links that are useful in this context. Except for Dawid's and Apache's pages, these are not associated with this project.
+
+* https://git-wip-us.apache.org/[Git at Apache] General Apache guidelines.
+* https://github.com/dweiss/lucene-git-guides[Dawid's guide] From our very own Dawid Weiss.
+* http://git.or.cz/course/svn.html[Git for SVN crash course] For people who know SVN but not Git.
+* http://lmgtfy.com/?q=Git+beginners+guide[Let Me Google That For You] I've wanted to paste a link to LMGTFY for a long time...
+
+
+The goal here is to provide a super-simple guide without getting off into the all the possibilities, and it will certainly seem "too simple" to sophisticated users. We all have to start somewhere.
+
+== Git defaults
+
+Here are some recommended defaults to configure Globally for Git:
+
+[console]
+----
+$ git config [--global] user.name <real-name>
+$ git config [--global] user.email <email>@apache.org
+----
+
+*Is this really recommended?*
+
+[console]
+----
+$ git config --global pull.rebase true
+----
+
+== Use a personal fork for branches
+
+For both contributors and committers, using personal forks to store feature branches is *strongly encouraged*.
+You can fork the `apache/solr` repository through the Github UI.
+
+Once you have forked Solr, you can add it as a git "remote" locally so that you can push your branches there.
+Then you can rename the official repo to "apache" to limit confusion.
+If you want to name you local fork something other than "fork", then replace "fork" with the name you want to use.
+
+[console]
+----
+$ git remote add fork <the git clone url that you get from github>"
+$ git fetch fork
+$ git remote rename origin apache
+----
+
+
+== Working with Branches
+
+For almost all development on Solr, it is recommended to create a feature branch in your fork and a Pull Request (PR) in Github.
+
+=== Creating a Branch
+
+Some feature work may be easier accomplished with a dedicated branch in Git.
+This allows several people to work together at once.
+Dawid's Git Page has details on how to create a branch and push it to the remote repository for others to pull and collaborate.
+
+[console]
+----
+$ git checkout apache/main
+$ git pull
+$ git checkout -b feature-name
+$ git push fork feature-name
+----
+
+From now on, you can add files, commit and use `git push fork feature-name` whenever you want to upload your changes.
+
+=== Creating a PR
+
+Once your feature branch has been pushed to your fork, you can create a PR via the Github UI.
+Go to https://github.com/apache/solr/pulls and click "New Pull Request".
+
+Since your feature branch lives on your fork, click "compare across forks".
+Choose your fork for the "head repository", the option on the *right* of the arrow.
+Then choose your feature branch right after it.
+
+Click "Create Pull Request", and choose a name that starts with "SOLR-####: ", so that your JIRA Issue will be linked to this PR.
+Also be sure to click "Allow edits and access to secrets by maintainers", so that you can collaborate with other committers.
+
+=== Keeping your branch up-to-date with main
+
+While working on your branch, you should periodically bring it up to date with "main".
+This will make eventual merging with main later simpler, because you resolve any conflicts as you go.
+
+The Github UI might allow you to do this, and if so it's perfectly safe to use that feature.
+If the Github UI tells you to do it manually, *DO NOT follow their instructions, use the following*:
+
+[console]
+----
+$ git fetch apache
+$ git checkout <branch> # This is the feature branch you want to bring up-to-date
+$ git merge apache/main
+----
+
+At this point, you likely have conflicts.
+You need to resolve those, and there are a number of ways to do that.
+
+Once the conflicts have been resolved:
+
+[console]
+----
+$ git commit # Commit the fixes for conflicts. The message may be already populated, edit it as needed but it's not very important.
+$ git push fork branch # Push the merged feature branch to your fork
+----
+
+=== Merging Your PR/Branch with main
+
+Once all development is done and you are ready to make your commit to `main`, the process should be easy.
+
+Since you have created a PR in Github, use the "Squash and Merge" option at the bottom of the PR.
+
+If this is grayed out and Github says that you have conflicts, use the xref:#_keeping_your_branch_up_to_date_with_main[Keeping your branch up-to-date with main] section to help.
+**DO NOT follow the Github instructions on how to do this, if you have to do it manually.**
+Once this is done, hopefully you have new commit(s) in your PR and the checks will re-run.
+Once those pass you will get a green box allowing you to "Squash and Merge".
+
+That's it! Yay!
+
+Make sure to xref:#_backporting_changes[backport] your commit if it needs to go into a minor or patch release!
+
+=== Using shared branches
+
+Some features require collaboration between many people.
+In this case multiple people need to be able to easily pull and push to a custom branch.
+
+This can be accomplished in two ways:
+* The Github Desktop app
+** Have someone create a branch and PR normally, as described above.
+Make sure they have clicked the checkbox "Allow edits and access to secrets by maintainers" when creating the PR.
+** Download the Github Desktop app.
+** Once you have the Solr repository added, you can checkout a PR and pull/push easily via the UI.
+* Have a feature branch in the apache repo.
+** Preferred practice is to name your branch `SOLR-XXXXX` (where "SOLR-XXXXX" is the JIRA ID), unless your feature does not yet have a single JIRA that's appropriate.
+In that case, you can use feature/<name>.
+If you name your branch in this way, commits to the branch will not pollute the comments of your JIRA issue.
+
+The Github Desktop app is strongly encouraged over a feature branch in the apache repository.
+However, if you do use a feature branch, make sure that it is deleted once development is done on it (merged to `main` or abandoned).
+
+== Simple commits
+
+For simple commits for simple JIRAs, when you do not expect to make a PR or have other people review the commit.
+
+Update your repo (perhaps with .gitconfig making this use rebasing)
+
+[,console]
+----
+$ git checkout origin/main
+----
+
+Make changes, get through `gradlew test` and `gradlew precommit` targets.
+
+[,console]
+----
+$ git add .
+$ git commit -m "SOLR####: additional comments, often the title of the JIRA" # (commits locally, nothing in ASF yet)
+$ git pull apache main
+$ git push apache main
+----
+
+Notes:
+
+At any time `git status` tells you whether you have anything local that isn't in sync with the branch you're on.
+This includes changes not committed locally, new files not added to the local repository.
+
+`git diff --stat apache/main` will show you committed (locally) but not pushed changes.
+
+If you omit the `-m` flag you'll find yourself in a vi-like editor where you can enter long commit messages.
+
+== Backporting changes
+
+Backporting changes from `main` to a branch like `branch_9x`.
+
+Thanks to Jan, we have a wonderful tool that will do most of the backporting for you.
+
+[console]
+----
+$ ./dev-tools/scripts/cherrypick.sh -b branch_9x -r apache -p <commit hash>
+----
+
+The above command will backport the commit hash you provide to `branch_9x` after running precommit first (the `-p` flag).
+If you need to backport to an additional branch, such as `branch_9_2`, you can add an additional `-b branch_9_2` to the command.
+If your remote that tracks the apache repo is not named "apache", then use a that name after the `-r` option.
+
+You should have seen the commit hash echoed when you committed to apache/main, if not and you included the SOLR-####, the JIRA will have it.
+Otherwise run `git checkout main && git log` and find the hash for the commit you want to backport.
+
+The backport might fail because the cherry pick has conflicts.
+If that's the case, then you can do the following.
+
+[console]
+----
+$ git status
+# Fix all necessary conflicts
+$ git add <conflicting files>
+$ git cherry-pick --continue
+$ ./gradlew check -x test
+$ git push apache branch_9x
+# Replace "apache" or "branch_9x" if you have a different repo name or backporting branch.
+----
+
+=== Backporting Manually
+
+If you need to backport manually, it's still pretty simple.
+The script above just does most of it for you
+
+[console]
+----
+$ git checkout apache/branch_9x
+$ git pull apache
+$ git cherry-pick <hash>
+$ ./gradlew check -x test # Run tests if you need to
+$ git show HEAD # This will show you the commit you are about to push, make sure it looks right
+$ git push apache branch_9x
+----
+
+There has been some issue with Solr's CHANGES.txt file "cherry picking" all of the changes for trunk, so check this file especially.
diff --git a/dev-docs/how-to-contribute.adoc b/dev-docs/how-to-contribute.adoc
@@ -4,6 +4,22 @@ The Apache Solr Github Repository is located here: https://github.com/apache/sol
 
 Please keep in mind that the project is community driven, with many members taking their own personal time to help respond to issue and review PRs. Be open to feedback and discussions and maintain a respectful approach. Read our https://solr.apache.org/community.html#code-of-conduct[code of conduct] for more.
 
+## Getting Your Feet Wet: Where to Begin?
+
+New to Solr? Want to find JIRA issues that you can work on without taking on the whole world?
+
+The Solr developers use the **newdev** label to mark issues that developers new to Solr might be interested in working on. The rough criteria used to make this selection are:
+
+* Nobody has done any work on the issue yet.
+* The issue is likely not controversial.
+* The issue is likely self-contained with limited scope.
+
+To see a list of open issues with the **newdev** label, look at this link https://s.apache.org/newdevsolr
+
+Note: Fixing these issues may require asking questions on the developer list to figure out what they mean - there is no guarantee that any of these will be either quick or easy.
+
+Emailing individual committers with questions about specific Solr issues is discouraged. See http://people.apache.org/~hossman/#private_q.
+
 ## Setup for Contributing
 In order to get setup you will need a fork of the Apache Solr repository and an account in the ASF Jira (usable for all Apache projects).
 
@@ -24,4 +40,34 @@ In order to make a new contribution to Solr you will use the fork you have creat
 * The PR will run a gradle pre-commit task that will do some basic checks of your changes. This is run as a Github Action and the results can be viewed from your PR.
 * If you properly named your PR you will see it automatically linked to your Jira issue when you view the issue.
 * If your PR is still a work in progress, you can use the https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests[PR Draft feature] of Github to denote draft status.
-5. At this point, you will need a Solr committer to review your change and help to get it merged upstream. You can use the https://solr.apache.org/community.html[Solr Developers Mailing List] to get attention to your issue.
+5. At this point, you will need a Solr committer to review your change and help to get it merged upstream. You can use the https://solr.apache.org/community.html[Solr Developers Mailing List] to get attention to your issue.
+
+## PR Do-s and Don't-s
+
+Please do not:
+
+* reformat code unrelated to the bug being fixed: formatting changes should be separate patches/commits.
+* comment out code that is now obsolete: just remove it.
+* insert comments around each change, marking the change: folks can use git to figure out what's changed and by whom.
+* make things public which are not required by end users.
+* Combine multiple issues into a single patch, especially if they are unrelated or only loosely related. This is true even if the changes affect the same files. In some rare cases it is warranted, but for the most part it makes it harder for committers to evaluate the patch.
+
+Please do:
+
+* try to adhere to the coding style of files you edit;
+* comment code whose function or rationale is not obvious;
+* update documentation (e.g., package.html files, this wiki, etc.)
+* try to provide a unit test that shows a bug was indeed fixed or the new functionality truly works
+* use the "draft state" for PRs which are work in progress
+
+## Getting Your Contribution Merged
+
+Please be patient.
+Committers are busy people too.
+If no one responds to your patch after a few days, please make friendly reminders.
+Please incorporate others suggestions into your patch if you think they're reasonable.
+Remember that even a patch/PR that is not committed is useful to the community.
+Supply your contribution as early as possible, and updates as often as possible during your work.
+This helps the rest of the community and committers to start understanding, help shaping, commenting on etc. your work throughout the entire process.
+Supplying a PR does not necessarily mean that it is complete and ready to be committed, it might also just be a way of communicating your idea and progress.
+It can be useful to set the PR to "Draft" status until you feel it is ready for broad review.