bmarwell commented on a change in pull request #77: URL: https://github.com/apache/shiro-site/pull/77#discussion_r577395053
########## File path: how-to-contribute.md ########## @@ -104,74 +99,101 @@ If you want to add a feature, you should bring it up for discussion on the dev@s In short, communication is a vital part of making a contribution to an Apache project. +<a name="HowtoContribute-git"></a> +<a name="HowtoContribute-GitUsage"></a> +##Git Usage + +An overview of how to use Git to participate in Shiro development. Beginners, do't be afraid - you cannot accidentally destroy the actual code repository, because you are working with a local copy as an anonymous user. Therefore, you do not have the system permissions to change anything. You can only update your local repository and compare your revisions with the real repository. The [Download Shiro](download.html "Download") page explains how to check-out the code base and build your local copy. + <a name="HowtoContribute-gettingStartedGit"></a> -###Getting Started +###Git, Getting Started -First, lets make sure that you've added your name and email to your `~/.gitconfig`: +Add your name and email to your `~/.gitconfig`: ``` bash $ git config --global user.name "Your Name" $ git config --global user.email [email protected] ``` -You'll grab the Shiro source with git: +Grab the Shiro source: ``` bash $ git clone https://gitbox.apache.org/repos/asf/shiro.git ``` -If you already have the source, make sure you're working with the most recent version. Do a `git pull` if you cloned the source more than a few hours ago. (Apache Shiro development can move pretty fast!) +Make sure you're working with the most recent version. Do a `git pull` if you cloned the source more than a few hours ago. ``` bash $ git checkout -b mybranch ``` Review comment: Maybe, while at it, change to github and let them fork the repository first. ########## File path: how-to-contribute.md ########## @@ -30,17 +44,21 @@ Document writers are usually the most wanted people so if you like to help but y You can be a huge help by providing extra assistance in any of the following areas: * Assisting to improve documentation and the website. -* Testing Shiro (especially its less-frequently-used features) on various configurations and reporting back. +* Testing Shiro on various configurations and reporting back, especially Shiro's less-frequently-used features. * New samples for the 'shiro-sample' to concisely describe and demonstrate features. Such samples can also enable automated testing. -* Debugging - producing reproducible test cases and/or finding causes of bugs. Most bugs are recorded as issues (see [explanation below](#HowtoContribute-procedure)). -* Providing new use-cases and requirements. If you think that Shiro does not quite meet your needs then tell us about it on the mailing list. -* Specifying/analysing/designing new features - and beyond. If you wish to get further involved with this, please join the [`shiro-dev` mailing list](mailing-lists.html "Mailing Lists"), install and try out Shiro and read some of the [mail archives](mailing-lists.html "Mailing Lists"). You should have a reasonable fluency in security technologies, some Java and Maven skills, and a basic understanding of the Shiro architecture - don't just say "it should have XYZ" without reading anything first - because chances are, somebody has already thought of that feature!) -* Packaging easy-to-install packages (such as RPMs) for the myriad of possible configurations out there. (The project does not maintain anything but the basic .zip and .tar.gz packages, but anyone is welcome to build their own specific packages and announce them on the forrest-dev list) -* ... and there is just one other thing - don't forget to tell everyone who asks, how great Shiro is! The more people that know about and start to use Shiro, the larger the pool of potential contributors will be. +* Debugging - producing reproducible test cases and/or finding causes of bugs. Most bugs are [recorded as issues](#HowtoContribute-procedure)). +* Providing new use-cases and requirements. +** If you think that Shiro does not quite meet your needs then tell us about it on the mailing list. +* Specifying, analysing or designing new features - and beyond. +** If you wish to get further involved with this, please join the [`shiro-dev` mailing list](mailing-lists.html "Mailing Lists"), install and try out Shiro and read some of the [mail archives](mailing-lists.html "Mailing Lists"). +*** Don't just say "it should have XYZ" without reading anything first - because chances are, somebody has already thought of that feature. +* Packaging easy-to-install packages (such as Red Hat Package Managers (RPM)) for the myriad of possible configurations out there. +** The project does not maintain anything but the basic .zip and .tar.gz packages, but anyone is welcome to build their own specific packages and announce those on the mailing list. +* ... and one more thing - don't forget to tell everyone, how great Shiro is! The more people that know about and start to use Shiro, the larger the pool of potential contributors will be. <a name="HowtoContribute-procedure"></a> <a name="HowtoContribute-Procedureforreportingbugsandissuesandenhancementsuggestions"></a> -##Procedure for reporting bugs and issues and enhancement suggestions +##Procedure for Reporting Bugs and Issues and Enhancement Suggestions Review comment: I am not sure about this capitalizations ########## File path: how-to-contribute.md ########## @@ -104,74 +99,101 @@ If you want to add a feature, you should bring it up for discussion on the dev@s In short, communication is a vital part of making a contribution to an Apache project. +<a name="HowtoContribute-git"></a> +<a name="HowtoContribute-GitUsage"></a> +##Git Usage Review comment: space after `#` ########## File path: how-to-contribute.md ########## @@ -104,74 +99,101 @@ If you want to add a feature, you should bring it up for discussion on the dev@s In short, communication is a vital part of making a contribution to an Apache project. +<a name="HowtoContribute-git"></a> +<a name="HowtoContribute-GitUsage"></a> +##Git Usage + +An overview of how to use Git to participate in Shiro development. Beginners, do't be afraid - you cannot accidentally destroy the actual code repository, because you are working with a local copy as an anonymous user. Therefore, you do not have the system permissions to change anything. You can only update your local repository and compare your revisions with the real repository. The [Download Shiro](download.html "Download") page explains how to check-out the code base and build your local copy. + <a name="HowtoContribute-gettingStartedGit"></a> -###Getting Started +###Git, Getting Started -First, lets make sure that you've added your name and email to your `~/.gitconfig`: +Add your name and email to your `~/.gitconfig`: ``` bash $ git config --global user.name "Your Name" $ git config --global user.email [email protected] ``` -You'll grab the Shiro source with git: +Grab the Shiro source: ``` bash $ git clone https://gitbox.apache.org/repos/asf/shiro.git ``` -If you already have the source, make sure you're working with the most recent version. Do a `git pull` if you cloned the source more than a few hours ago. (Apache Shiro development can move pretty fast!) +Make sure you're working with the most recent version. Do a `git pull` if you cloned the source more than a few hours ago. ``` bash $ git checkout -b mybranch ``` -This does two things: One, it creates the branch mybranch and two, it changes your working branch to mybranch. Running `git branch` will show you which branch you're working on, with an asterisk next to the active branch, like so: +This does two things: +* creates the branch mybranch +* changes your working branch to mybranch. +Running `git branch` will show you which branch you're working on, with an asterisk next to the active branch. ``` bash [user@localhost shiro]$ git branch master * mybranch ``` -Make whatever changes you're going to make, be sure to use git add to stage the changes, and then you're going to commit the changes to your working branch: +Use `git add` to stage the changes. Commit the changes to your working branch: ``` bash git commit -m "Insert a meaningful summary of changes here." ``` -Finally, you can create a patch and attach it to the JIRA issue that you created for the bug you are fixing. +Finally, you can create a patch and attach it to the JIRA issue: ``` bash git format-patch master --stdout > ~/patch-name.patch ``` +* When sending a patch, you usually do not need to worry about which Git branch it should be applied to. The maintainers of the repository will decide. +* Every contribution is worthwhile! Even when the code isn't perfect or documentation has typos. Even if you got it wrong the first time around. Any contribution is a start of something special. Through your continued effort and the help of the community, your contribution will evolve. + <a name="HowtoContribute-review"></a> ###Review -Once you've submitted your pull request, you should receive a response within a few days. If you receive no response within a week, please ping the shiro-dev mailing list ([email protected]). +Fter submitting pull request, you should receive a response within a few days. If you receive no response within a week, please send a message to the shiro-dev mailing list ([email protected]). + +<a name="HowtoContribute-committer"></a> +<a name="HowtoContribute-GitCommitters"></a> +##Git Committers + +After a developer has consistently provided contributions such as code, documentation and discussion, and demonstrated committment, then the rest of the dev community may vote to grant this developer commit access to the Git repository. See the [ASF developers resources](http://www.apache.org/dev/) and especially the [Source code repositories](http://www.apache.org/dev/version-control.html). + +<a name="HowtoContribute-patches"></a> +<a name="HowtoContribute-Howtoprepareandcontributepatches"></a> +##Contributing as a Non-Committer + +Non-committers, have to submit patches for review. Apache Shiro accepts GitHub pull requests. + +Apache Shiro has a read-only mirror on GitHub that is kept in sync with the canonical Git repo maintained by the Apache Software Foundation. For detailed instructions see the [GitHub Contribution Guidelines](https://github.com/apache/shiro/blob/master/CONTRIBUTING.md). <a name="HowtoContribute-tips"></a> <a name="HowtoContribute-ContributionNotesandTips"></a> ##Contribution Notes and Tips This is a collection of tips for contributing to the project in a manner that is productive for all parties. -* See general ASF [Tips for email contributors](http://www.apache.org/dev/contrib-email-tips.html) -* There is no such thing as a dumb question. Always check the [archives](mailing-lists.html "Mailing Lists") to see if someone else asked it first and maybe already received an answer. -* Every contribution is worthwhile. Even if the code isn't perfect. Even if the documentation has typos. Even if you got it wrong the first time around. Any contribution is a start of something special. Through your continued effort and the help of the community, your contribution will evolve and get ever closer to "perfect". -* Use sensible and concise email subject headings. Search engines, and humans trying to browse a voluminous list, will respond favourably to a descriptive title. -* Start new threads with new Subject for new topics, rather than reusing the previous Subject line. -* Keep each topic focused. If some new topic arises then start a new discussion. This leaves the original topic to continue uncluttered. - Whenever you decide to start a new topic, then start with a fresh new email message window. Do not use the "Reply to" button, because threaded mail-readers get confused (they utilise the In-reply-to header). If so, then your new topic will get lost in the previous thread and go unanswered. -* Prepend your email subject line with a marker when that is appropriate, e.g. [Proposal], [RT] (Random Thought which quickly blossom into research topics <i class="fa fa-smile-o" aria-hidden="true"></i>, [STATUS] (development status of a certain facility). -* Remember that most people are participating in development on a volunteer basis and in their "spare time". These enthusiasts will attempt to respond to issues. It may take a little while to get your answers. -* Research your topic thoroughly before beginning to discuss a new development issue. Search and browse through the email archives - your issue may have been discussed before. Do not just perceive a problem and then rush out with a question - instead, delve. +###Links +* [Tips for email contributors](http://www.apache.org/dev/contrib-email-tips.html) +* Old questions and answers in [archives](mailing-lists.html "Mailing Lists"). + +* There are no dumb questions. But browse, search and learn from mailing list archives. +* Research your topic thoroughly before beginning to discuss a new development issue. + +###Emails +* Start new threads with new Subject for new topics, rather than reusing the previous Subject line. Use a descriptive title! +** Clearly explain your issue and write a concise email message. * Try to at least offer a partial solution and not just a problem statement. -* Take the time to clearly explain your issue and write a concise email message. Less confusion facilitates fast and complete resolution. -* Do not bother to send an email reply that simply says "thanks". When the issue is resolved, that is the finish - end of thread. Reduce clutter. -* You would usually do any development work against the master branch in Git. -* When sending a patch, you usually do not need to worry about which Git branch it should be applied to. The maintainers of the repository will decide. -* Keep all project-related discussion on the mailing list. It is much better to utilise the wider audience, rather than to break off into private discussion groups. You never know who else will have the answer to your issues, and anyway other people are interested in the outcome. -* Become familiar with the mailing lists. As you browse and search, you will see the way other people do things. Follow the leading examples. +* Prepend your email subject line with a marker when that is appropriate, e.g.: +** [Proposal] +** [RT] (Random Thought which quickly blossom into research topics) +** [STATUS] (development status of a certain facility) + +* Reduce clutter, don't send an e-mail which simply says "thanks". +* Keep all project-related discussion on the mailing list. It is better to utilise the wider audience, rather than to break off into private discussions. You never know who else will have the answer to your issues, and anyway other people are interested in the outcome. Review comment: while at it, please only one space after `*` or `**` ########## File path: how-to-contribute.md ########## @@ -104,74 +99,101 @@ If you want to add a feature, you should bring it up for discussion on the dev@s In short, communication is a vital part of making a contribution to an Apache project. +<a name="HowtoContribute-git"></a> +<a name="HowtoContribute-GitUsage"></a> +##Git Usage + +An overview of how to use Git to participate in Shiro development. Beginners, do't be afraid - you cannot accidentally destroy the actual code repository, because you are working with a local copy as an anonymous user. Therefore, you do not have the system permissions to change anything. You can only update your local repository and compare your revisions with the real repository. The [Download Shiro](download.html "Download") page explains how to check-out the code base and build your local copy. + <a name="HowtoContribute-gettingStartedGit"></a> -###Getting Started +###Git, Getting Started -First, lets make sure that you've added your name and email to your `~/.gitconfig`: +Add your name and email to your `~/.gitconfig`: ``` bash $ git config --global user.name "Your Name" $ git config --global user.email [email protected] ``` -You'll grab the Shiro source with git: +Grab the Shiro source: ``` bash $ git clone https://gitbox.apache.org/repos/asf/shiro.git ``` -If you already have the source, make sure you're working with the most recent version. Do a `git pull` if you cloned the source more than a few hours ago. (Apache Shiro development can move pretty fast!) +Make sure you're working with the most recent version. Do a `git pull` if you cloned the source more than a few hours ago. ``` bash $ git checkout -b mybranch ``` -This does two things: One, it creates the branch mybranch and two, it changes your working branch to mybranch. Running `git branch` will show you which branch you're working on, with an asterisk next to the active branch, like so: +This does two things: +* creates the branch mybranch +* changes your working branch to mybranch. +Running `git branch` will show you which branch you're working on, with an asterisk next to the active branch. ``` bash [user@localhost shiro]$ git branch master * mybranch ``` -Make whatever changes you're going to make, be sure to use git add to stage the changes, and then you're going to commit the changes to your working branch: +Use `git add` to stage the changes. Commit the changes to your working branch: ``` bash git commit -m "Insert a meaningful summary of changes here." ``` -Finally, you can create a patch and attach it to the JIRA issue that you created for the bug you are fixing. +Finally, you can create a patch and attach it to the JIRA issue: ``` bash git format-patch master --stdout > ~/patch-name.patch ``` +* When sending a patch, you usually do not need to worry about which Git branch it should be applied to. The maintainers of the repository will decide. +* Every contribution is worthwhile! Even when the code isn't perfect or documentation has typos. Even if you got it wrong the first time around. Any contribution is a start of something special. Through your continued effort and the help of the community, your contribution will evolve. + <a name="HowtoContribute-review"></a> ###Review -Once you've submitted your pull request, you should receive a response within a few days. If you receive no response within a week, please ping the shiro-dev mailing list ([email protected]). +Fter submitting pull request, you should receive a response within a few days. If you receive no response within a week, please send a message to the shiro-dev mailing list ([email protected]). + +<a name="HowtoContribute-committer"></a> +<a name="HowtoContribute-GitCommitters"></a> +##Git Committers + +After a developer has consistently provided contributions such as code, documentation and discussion, and demonstrated committment, then the rest of the dev community may vote to grant this developer commit access to the Git repository. See the [ASF developers resources](http://www.apache.org/dev/) and especially the [Source code repositories](http://www.apache.org/dev/version-control.html). + +<a name="HowtoContribute-patches"></a> +<a name="HowtoContribute-Howtoprepareandcontributepatches"></a> +##Contributing as a Non-Committer + +Non-committers, have to submit patches for review. Apache Shiro accepts GitHub pull requests. + +Apache Shiro has a read-only mirror on GitHub that is kept in sync with the canonical Git repo maintained by the Apache Software Foundation. For detailed instructions see the [GitHub Contribution Guidelines](https://github.com/apache/shiro/blob/master/CONTRIBUTING.md). <a name="HowtoContribute-tips"></a> <a name="HowtoContribute-ContributionNotesandTips"></a> ##Contribution Notes and Tips This is a collection of tips for contributing to the project in a manner that is productive for all parties. -* See general ASF [Tips for email contributors](http://www.apache.org/dev/contrib-email-tips.html) -* There is no such thing as a dumb question. Always check the [archives](mailing-lists.html "Mailing Lists") to see if someone else asked it first and maybe already received an answer. -* Every contribution is worthwhile. Even if the code isn't perfect. Even if the documentation has typos. Even if you got it wrong the first time around. Any contribution is a start of something special. Through your continued effort and the help of the community, your contribution will evolve and get ever closer to "perfect". -* Use sensible and concise email subject headings. Search engines, and humans trying to browse a voluminous list, will respond favourably to a descriptive title. -* Start new threads with new Subject for new topics, rather than reusing the previous Subject line. -* Keep each topic focused. If some new topic arises then start a new discussion. This leaves the original topic to continue uncluttered. - Whenever you decide to start a new topic, then start with a fresh new email message window. Do not use the "Reply to" button, because threaded mail-readers get confused (they utilise the In-reply-to header). If so, then your new topic will get lost in the previous thread and go unanswered. -* Prepend your email subject line with a marker when that is appropriate, e.g. [Proposal], [RT] (Random Thought which quickly blossom into research topics <i class="fa fa-smile-o" aria-hidden="true"></i>, [STATUS] (development status of a certain facility). -* Remember that most people are participating in development on a volunteer basis and in their "spare time". These enthusiasts will attempt to respond to issues. It may take a little while to get your answers. -* Research your topic thoroughly before beginning to discuss a new development issue. Search and browse through the email archives - your issue may have been discussed before. Do not just perceive a problem and then rush out with a question - instead, delve. +###Links +* [Tips for email contributors](http://www.apache.org/dev/contrib-email-tips.html) +* Old questions and answers in [archives](mailing-lists.html "Mailing Lists"). + +* There are no dumb questions. But browse, search and learn from mailing list archives. +* Research your topic thoroughly before beginning to discuss a new development issue. + +###Emails Review comment: space after `#` ########## File path: how-to-contribute.md ########## @@ -104,74 +99,101 @@ If you want to add a feature, you should bring it up for discussion on the dev@s In short, communication is a vital part of making a contribution to an Apache project. +<a name="HowtoContribute-git"></a> +<a name="HowtoContribute-GitUsage"></a> +##Git Usage + +An overview of how to use Git to participate in Shiro development. Beginners, do't be afraid - you cannot accidentally destroy the actual code repository, because you are working with a local copy as an anonymous user. Therefore, you do not have the system permissions to change anything. You can only update your local repository and compare your revisions with the real repository. The [Download Shiro](download.html "Download") page explains how to check-out the code base and build your local copy. + <a name="HowtoContribute-gettingStartedGit"></a> -###Getting Started +###Git, Getting Started -First, lets make sure that you've added your name and email to your `~/.gitconfig`: +Add your name and email to your `~/.gitconfig`: ``` bash $ git config --global user.name "Your Name" $ git config --global user.email [email protected] ``` -You'll grab the Shiro source with git: +Grab the Shiro source: ``` bash $ git clone https://gitbox.apache.org/repos/asf/shiro.git ``` -If you already have the source, make sure you're working with the most recent version. Do a `git pull` if you cloned the source more than a few hours ago. (Apache Shiro development can move pretty fast!) +Make sure you're working with the most recent version. Do a `git pull` if you cloned the source more than a few hours ago. ``` bash $ git checkout -b mybranch ``` -This does two things: One, it creates the branch mybranch and two, it changes your working branch to mybranch. Running `git branch` will show you which branch you're working on, with an asterisk next to the active branch, like so: +This does two things: +* creates the branch mybranch +* changes your working branch to mybranch. +Running `git branch` will show you which branch you're working on, with an asterisk next to the active branch. ``` bash [user@localhost shiro]$ git branch master * mybranch ``` -Make whatever changes you're going to make, be sure to use git add to stage the changes, and then you're going to commit the changes to your working branch: +Use `git add` to stage the changes. Commit the changes to your working branch: ``` bash git commit -m "Insert a meaningful summary of changes here." ``` -Finally, you can create a patch and attach it to the JIRA issue that you created for the bug you are fixing. +Finally, you can create a patch and attach it to the JIRA issue: ``` bash git format-patch master --stdout > ~/patch-name.patch ``` +* When sending a patch, you usually do not need to worry about which Git branch it should be applied to. The maintainers of the repository will decide. +* Every contribution is worthwhile! Even when the code isn't perfect or documentation has typos. Even if you got it wrong the first time around. Any contribution is a start of something special. Through your continued effort and the help of the community, your contribution will evolve. + <a name="HowtoContribute-review"></a> ###Review -Once you've submitted your pull request, you should receive a response within a few days. If you receive no response within a week, please ping the shiro-dev mailing list ([email protected]). +Fter submitting pull request, you should receive a response within a few days. If you receive no response within a week, please send a message to the shiro-dev mailing list ([email protected]). + +<a name="HowtoContribute-committer"></a> +<a name="HowtoContribute-GitCommitters"></a> +##Git Committers + +After a developer has consistently provided contributions such as code, documentation and discussion, and demonstrated committment, then the rest of the dev community may vote to grant this developer commit access to the Git repository. See the [ASF developers resources](http://www.apache.org/dev/) and especially the [Source code repositories](http://www.apache.org/dev/version-control.html). + +<a name="HowtoContribute-patches"></a> +<a name="HowtoContribute-Howtoprepareandcontributepatches"></a> +##Contributing as a Non-Committer + +Non-committers, have to submit patches for review. Apache Shiro accepts GitHub pull requests. + +Apache Shiro has a read-only mirror on GitHub that is kept in sync with the canonical Git repo maintained by the Apache Software Foundation. For detailed instructions see the [GitHub Contribution Guidelines](https://github.com/apache/shiro/blob/master/CONTRIBUTING.md). <a name="HowtoContribute-tips"></a> <a name="HowtoContribute-ContributionNotesandTips"></a> ##Contribution Notes and Tips This is a collection of tips for contributing to the project in a manner that is productive for all parties. -* See general ASF [Tips for email contributors](http://www.apache.org/dev/contrib-email-tips.html) -* There is no such thing as a dumb question. Always check the [archives](mailing-lists.html "Mailing Lists") to see if someone else asked it first and maybe already received an answer. -* Every contribution is worthwhile. Even if the code isn't perfect. Even if the documentation has typos. Even if you got it wrong the first time around. Any contribution is a start of something special. Through your continued effort and the help of the community, your contribution will evolve and get ever closer to "perfect". -* Use sensible and concise email subject headings. Search engines, and humans trying to browse a voluminous list, will respond favourably to a descriptive title. -* Start new threads with new Subject for new topics, rather than reusing the previous Subject line. -* Keep each topic focused. If some new topic arises then start a new discussion. This leaves the original topic to continue uncluttered. - Whenever you decide to start a new topic, then start with a fresh new email message window. Do not use the "Reply to" button, because threaded mail-readers get confused (they utilise the In-reply-to header). If so, then your new topic will get lost in the previous thread and go unanswered. -* Prepend your email subject line with a marker when that is appropriate, e.g. [Proposal], [RT] (Random Thought which quickly blossom into research topics <i class="fa fa-smile-o" aria-hidden="true"></i>, [STATUS] (development status of a certain facility). -* Remember that most people are participating in development on a volunteer basis and in their "spare time". These enthusiasts will attempt to respond to issues. It may take a little while to get your answers. -* Research your topic thoroughly before beginning to discuss a new development issue. Search and browse through the email archives - your issue may have been discussed before. Do not just perceive a problem and then rush out with a question - instead, delve. +###Links Review comment: Space after `#` ########## File path: how-to-contribute.md ########## @@ -50,51 +68,28 @@ The Roadmap is the best way to get an overview. The Unscheduled list also needs When creating a new issue, please provide a concise Summary Title and a short Description. Add further information as Comments and include links to the mail archives. The normal procedure is to discuss the issue on the mailing list and then add relevant notes to the issue tracker, otherwise it becomes cluttered. -<a name="HowtoContribute-git"></a> -<a name="HowtoContribute-GitUsage"></a> -##Git Usage - -An overview of how to use Git to participate in Shiro development. Do not be afraid - you cannot accidentally destroy the actual code repository, because you are working with a local copy as an anonymous user. Therefore, you do not have the system permissions to change anything. You can only update your local repository and compare your revisions with the real repository. The [Download Shiro](download.html "Download") page explains how to check-out the code base and build your local copy. - -<a name="HowtoContribute-committer"></a> -<a name="HowtoContribute-GitCommitters"></a> -## Git Committers - -After a developer has consistently provided contributions (code, documentation and discussion) and demonstrated committment, then the rest of the dev community may vote to grant this developer commit access to the Git repository. See the [ASF developers resources](http://www.apache.org/dev/) especially the [Source code repositories](http://www.apache.org/dev/version-control.html). - <a name="HowtoContribute-issues"></a> <a name="HowtoContribute-ProcedureforRaisingDevelopmentIssues"></a> -## Procedure for Raising Development Issues - -There are two methods for discussing development and submitting patches. So that everyone can be productive, it is important to know which method is appropriate for a certain situation and how to go about it without confusion. This section explains when to use the developer [mailing list](mailing-lists.html "Mailing Lists") and the [issue tracker](https://issues.apache.org/jira/browse/SHIRO). - -Research your topic thoroughly before beginning to discuss a new development issue. Search and browse through the email archives - your issue may have been discussed before. Prepare your post clearly and concisely. - -Most issues will be discovered, resolved, and then patched quickly via the developer mailing list. Larger issues, and ones that are not yet fully understood or are hard to solve, are destined for the issue tracker. +##Procedure for Raising Development Issues -Experienced developers use the issue tracker directly, as they are very sure when they have found a bug and when not. However, less experienced users should first discuss it on the user or developer mailing list (as appropriate). Impatient people always enter everything into the issue tracker without caring if it is a bug of Shiro or their own installation/configuration mistake - please do not do this. +There are two methods for discussing development and submitting patches. So that everyone can be productive, it is important to know which method is appropriate for a certain situation and how to go about it without confusion. -As a rule-of-thumb, discuss an issue on the developers mailing list first to work out any details. After it is confirmed to be worthwhile, and you are clear about it, then submit the bug description or patch via Bug Tracking. +###Mailing List -Perhaps you do not get any answer on your first reply, so just post it again until you get one. (But please not every hour - allow a few days for the list to deal with it.) Bear in mind that other countries will have holidays at different times to your country and that they are in different time zones. You might also consider rewriting your initial posting. It may have not been clear to the readers on the mailing list. +Research your topic thoroughly before beginning to discuss a new development issue on the [mailing list](mailing-lists.html "Mailing Lists"). Search and browse through the email archives - your issue may have been discussed before. Prepare your post clearly and concisely. -<a name="HowtoContribute-patches"></a> -<a name="HowtoContribute-Howtoprepareandcontributepatches"></a> -##Contributing as a Non-Committer - -If you're a committer on an Apache project, it means that you can commit directly to the project's repository. For instance, with Apache Shiro committers are allowed to directly push commits into the git repository. +Most issues will be discovered, resolved, and then patched quickly via the developer mailing list. Larger issues, and ones that are not yet fully understood or are hard to solve, are destined for the issue tracker. -Non-committers, however, have to submit patches for review. Apache Shiro accepts GitHub pull requests. If you are new to Git and GitHub, check these two links: +###Issue Tracker -* [GitHub 15 minutes tutorial](https://try.github.io/levels/1/challenges/1) -* [Creating Pull Requests](https://help.github.com/articles/creating-a-pull-request/) +Experienced developers use the [issue tracker](https://issues.apache.org/jira/browse/SHIRO) directly, as they are very sure when they have found a bug and when not. Less experienced users should first discuss it on the user or developer mailing list (as appropriate). Impatient people always enter everything into the issue tracker without caring if it is a bug of Shiro ,or their own installation/configuration mistake - please do not do this. -Apache Shiro has a read-only mirror on GitHub that is kept in sync with the canonical Git repo maintained by the Apache Software Foundation. Submitting GitHub pull requests is the easiest way to get your contribution upstream. For detailed instructions see the link below: +Discuss an issue on the developers mailing list first to work out any details. After it is confirmed to be worthwhile, and you are clear about it, then submit the bug description or patch via Bug Tracking.. -[GitHub Contribution Guidelines](https://github.com/apache/shiro/blob/master/CONTRIBUTING.md) +Perhaps you do not get any answer on your first reply, so just post it again until you get one. But please not every hour - allow a few days for the list to deal with it. Bear in mind that other countries will have holidays at different times to your country and that they are in different time zones. You might also consider rewriting your initial posting. It may have not been clear to the readers on the mailing list. <a name="HowtoContribute-submitThroughJIRA"></a> -###Submitting a patch through JIRA +###Submitting a Patch Through JIRA Review comment: why the capitalization? ########## File path: how-to-contribute.md ########## @@ -104,74 +99,101 @@ If you want to add a feature, you should bring it up for discussion on the dev@s In short, communication is a vital part of making a contribution to an Apache project. +<a name="HowtoContribute-git"></a> +<a name="HowtoContribute-GitUsage"></a> +##Git Usage + +An overview of how to use Git to participate in Shiro development. Beginners, do't be afraid - you cannot accidentally destroy the actual code repository, because you are working with a local copy as an anonymous user. Therefore, you do not have the system permissions to change anything. You can only update your local repository and compare your revisions with the real repository. The [Download Shiro](download.html "Download") page explains how to check-out the code base and build your local copy. + <a name="HowtoContribute-gettingStartedGit"></a> -###Getting Started +###Git, Getting Started Review comment: space after `#`, maybe "getting started with git". If this is "getting started with git", where is "getting started with code/development/etc"? ########## File path: how-to-contribute.md ########## @@ -104,74 +99,101 @@ If you want to add a feature, you should bring it up for discussion on the dev@s In short, communication is a vital part of making a contribution to an Apache project. +<a name="HowtoContribute-git"></a> +<a name="HowtoContribute-GitUsage"></a> +##Git Usage + +An overview of how to use Git to participate in Shiro development. Beginners, do't be afraid - you cannot accidentally destroy the actual code repository, because you are working with a local copy as an anonymous user. Therefore, you do not have the system permissions to change anything. You can only update your local repository and compare your revisions with the real repository. The [Download Shiro](download.html "Download") page explains how to check-out the code base and build your local copy. + <a name="HowtoContribute-gettingStartedGit"></a> -###Getting Started +###Git, Getting Started -First, lets make sure that you've added your name and email to your `~/.gitconfig`: +Add your name and email to your `~/.gitconfig`: ``` bash $ git config --global user.name "Your Name" $ git config --global user.email [email protected] ``` -You'll grab the Shiro source with git: +Grab the Shiro source: ``` bash $ git clone https://gitbox.apache.org/repos/asf/shiro.git ``` -If you already have the source, make sure you're working with the most recent version. Do a `git pull` if you cloned the source more than a few hours ago. (Apache Shiro development can move pretty fast!) +Make sure you're working with the most recent version. Do a `git pull` if you cloned the source more than a few hours ago. ``` bash $ git checkout -b mybranch ``` -This does two things: One, it creates the branch mybranch and two, it changes your working branch to mybranch. Running `git branch` will show you which branch you're working on, with an asterisk next to the active branch, like so: +This does two things: +* creates the branch mybranch +* changes your working branch to mybranch. +Running `git branch` will show you which branch you're working on, with an asterisk next to the active branch. ``` bash [user@localhost shiro]$ git branch master * mybranch ``` -Make whatever changes you're going to make, be sure to use git add to stage the changes, and then you're going to commit the changes to your working branch: +Use `git add` to stage the changes. Commit the changes to your working branch: Review comment: Why the capitalization again? ---------------------------------------------------------------- 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. For queries about this service, please contact Infrastructure at: [email protected]
