You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@solr.apache.org by "epugh (via GitHub)" <gi...@apache.org> on 2023/04/13 15:30:37 UTC
[GitHub] [solr] epugh opened a new pull request, #1561: SOLR-16746: Migrate How to Contribute Content from cwiki
epugh opened a new pull request, #1561:
URL: https://github.com/apache/solr/pull/1561
https://issues.apache.org/jira/browse/SOLR-16746
# Description
Content is hidden in Confluence wiki, is out of date, and hard to update.
# Solution
Migrate content
# Tests
manual
# Checklist
Please review the following and check all that apply:
- [ ] I have reviewed the guidelines for [How to Contribute](https://wiki.apache.org/solr/HowToContribute) and my code conforms to the standards described there to the best of my ability.
- [ ] I have created a Jira issue and added the issue ID to my pull request title.
- [ ] I have given Solr maintainers [access](https://help.github.com/en/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork) to contribute to my PR branch. (optional but recommended)
- [ ] I have developed this patch against the `main` branch.
- [ ] I have run `./gradlew check`.
- [ ] I have added tests for my changes.
- [ ] I have added documentation for the [Reference Guide](https://github.com/apache/solr/tree/main/solr/solr-ref-guide)
--
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: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] HoustonPutman commented on pull request #1561: SOLR-16746: Migrate How to Contribute Content from cwiki
Posted by "HoustonPutman (via GitHub)" <gi...@apache.org>.
HoustonPutman commented on PR #1561:
URL: https://github.com/apache/solr/pull/1561#issuecomment-1507279304
Ok I made a ton of changes to the git page, better reflecting best practices and using asciidoc stuff instead of markdown.
--
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: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] epugh commented on pull request #1561: SOLR-16746: Migrate How to Contribute Content from cwiki
Posted by "epugh (via GitHub)" <gi...@apache.org>.
epugh commented on PR #1561:
URL: https://github.com/apache/solr/pull/1561#issuecomment-1507356785
G
> Also can we make a folder for these called `dev-docs/contributing`. Much better than having a lot of random docs mixed together.
I'm excited that we are building enough docs in `dev-docs` to start thinking about nesting... Having said that, I don't think we actually have enough for a multiples in in a `dev-docs/contributing`? What structure are you thinking would go in there.....?
--
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: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] epugh commented on a diff in pull request #1561: SOLR-16746: Migrate How to Contribute Content from cwiki
Posted by "epugh (via GitHub)" <gi...@apache.org>.
epugh commented on code in PR #1561:
URL: https://github.com/apache/solr/pull/1561#discussion_r1165799913
##########
dev-docs/git.adoc:
##########
@@ -0,0 +1,240 @@
+= 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
+----
+
+Git may prompt you to `git rebase --continue`, if conflicts are resolved, that should end up in the same place, of prompting you to git push your final changes to the remote repository.
Review Comment:
I think we should remove this... It's easier to add new docs versus get rid of them...
--
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: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] HoustonPutman commented on pull request #1561: SOLR-16746: Migrate How to Contribute Content from cwiki
Posted by "HoustonPutman (via GitHub)" <gi...@apache.org>.
HoustonPutman commented on PR #1561:
URL: https://github.com/apache/solr/pull/1561#issuecomment-1507363704
Yeah maybe there aren't enough files yet, but something to think about in the future!
--
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: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] epugh merged pull request #1561: SOLR-16746: Migrate How to Contribute Content from cwiki
Posted by "epugh (via GitHub)" <gi...@apache.org>.
epugh merged PR #1561:
URL: https://github.com/apache/solr/pull/1561
--
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: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] HoustonPutman commented on a diff in pull request #1561: SOLR-16746: Migrate How to Contribute Content from cwiki
Posted by "HoustonPutman (via GitHub)" <gi...@apache.org>.
HoustonPutman commented on code in PR #1561:
URL: https://github.com/apache/solr/pull/1561#discussion_r1165794950
##########
dev-docs/git.adoc:
##########
@@ -0,0 +1,240 @@
+= 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
+----
+
+Git may prompt you to `git rebase --continue`, if conflicts are resolved, that should end up in the same place, of prompting you to git push your final changes to the remote repository.
Review Comment:
After my changes, I don't think this is the case. There shouldn't be any rebase command used...
##########
dev-docs/git.adoc:
##########
@@ -0,0 +1,240 @@
+= 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
+----
+
+Git may prompt you to `git rebase --continue`, if conflicts are resolved, that should end up in the same place, of prompting you to git push your final changes to the remote repository.
+
+You may want to consider doing `git merge --squash main` - this will merge all commits from `main` into a single commit locally.
Review Comment:
I'm not sure this is really necessary either. Github will filter out all of the merged commits in the PR view.
--
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: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
[GitHub] [solr] HoustonPutman commented on pull request #1561: SOLR-16746: Migrate How to Contribute Content from cwiki
Posted by "HoustonPutman (via GitHub)" <gi...@apache.org>.
HoustonPutman commented on PR #1561:
URL: https://github.com/apache/solr/pull/1561#issuecomment-1507290818
Also can we make a folder for these called `dev-docs/contributing`. Much better than having a lot of random docs mixed together.
--
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: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org