You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@shiro.apache.org by bm...@apache.org on 2021/09/10 20:56:43 UTC
[shiro-site] 06/06: [JBake] convert features.md and
how-to-contribute.md.
This is an automated email from the ASF dual-hosted git repository.
bmarwell pushed a commit to branch jbake
in repository https://gitbox.apache.org/repos/asf/shiro-site.git
commit 3478318443daaf65decd6f6461551d2433e3fdf3
Author: Benjamin Marwell <bm...@apache.org>
AuthorDate: Fri Sep 10 22:24:25 2021 +0200
[JBake] convert features.md and how-to-contribute.md.
---
features.md | 34 -----
jbake/content/features.adoc | 36 +++++
.../content/how-to-contribute.adoc | 148 ++++++++++-----------
3 files changed, 105 insertions(+), 113 deletions(-)
diff --git a/features.md b/features.md
deleted file mode 100644
index f6e7e69..0000000
--- a/features.md
+++ /dev/null
@@ -1,34 +0,0 @@
-title: Features-ApacheShiroFeaturesOverview
-
-#Apache Shiro Features Overview
-
-Apache Shiro aims to be the most comprehensive, but also the easiest to use Java security framework available. Here are some of the frameworks finer points:
-
-* The easiest to understand Java Security API anywhere. Class and Interface names are intuitive and _make sense_. Anything is pluggable but good defaults exist for everything.
-
-* Support [authentication](authentication-features.html) ('logins') across one or more pluggable data sources (LDAP, JDBC, ActiveDirectory, etc).
-
-* Perform [authorization](authorization-features.html) ('access control') based on roles or fine-grained [permissions](permissions.html), also using pluggable data sources.
-
-* First-class [caching](caching.html) support for enhanced application performance.
-
-* Built-in POJO-based Enterprise [Session Management](session-management-features.html). Use in both web and non-web environments or in any environment where Single Sign On (SSO) or clustered or distributed sessions are desired.
-
-* _Heterogeneous_ client session access. You are no longer forced to use only the <tt>httpSession</tt> or Stateful Session Beans, which often unnecessarily tie applications to specific environments. Flash applets, C# applications, Java Web Start, and Web Applications, etc. can now all share session state regardless of deployment environment.
-
-* Simple Single Sign-On (SSO) support piggybacking the above Enterprise Session Management. If sessions are federated across multiple applications, the user's authentication state can be shared too. Log in once to any application and the others all recognize that log-in.
-
-* Secure data with the easiest possible [Cryptography](cryptography-features.html) APIs available, giving you power and simplicity beyond what Java provides by default for ciphers and hashes.
-
-* An incredibly robust yet _low-configuration_ web framework that can secure any url or resource, automatically handle logins and logouts, perform Remember Me services, and more.
-
-* Extremely low number of required dependencies. Standalone configuration requires only <tt>slf4j-api.jar</tt> and one of slf4j's binding .jars. Web configuration additionally requires <tt>commons-beanutils-core.jar</tt>. Feature-based dependencies (Ehcache caching, Quartz-based Session validation, Spring dependency injection, etc.) can be added when needed.
-
-##Want more information on what Shiro can do?
-
-Check out the specific features for each of Shiro's major components: [Authentication](authentication-features.html "Authentication Features"), [Authorization](authorization-features.html "Authorization Features"), [Session Management](session-management-features.html "Session Management Features"), and [Cryptography](cryptography-features.html "Cryptography Features").
-
-##Get Started in 10 Minutes with Shiro
-
-Try out Shiro for yourself with our [10 Minute Tutorial](10-minute-tutorial.html "10 Minute Tutorial"). And if you have any questions about Shiro, please check out our [community forum](forums.html "Forums") or [user mailing list](mailing-lists.html "Mailing Lists") for answers from the community.
-<input type="hidden" id="ghEditPage" value="features.md"></input>
diff --git a/jbake/content/features.adoc b/jbake/content/features.adoc
new file mode 100644
index 0000000..2b145a2
--- /dev/null
+++ b/jbake/content/features.adoc
@@ -0,0 +1,36 @@
+= Apache Shiro Features Overview
+:jbake-type: page
+:jbake-status: published
+:jbake-tags: documentation, overview, features
+:idprefix:
+:icons: font
+
+Apache Shiro aims to be the most comprehensive, but also the easiest to use Java security framework available. Here are some of the frameworks finer points:
+
+* The easiest to understand Java Security API anywhere. Class and Interface names are intuitive and _make sense_. Anything is pluggable but good defaults exist for everything.
+
+* Support link:authentication-features.html[authentication] ('logins') across one or more pluggable data sources (LDAP, JDBC, ActiveDirectory, etc).
+
+* Perform link:authorization-features.html[authorization] ('access control') based on roles or fine-grained link:permissions.html[permissions], also using pluggable data sources.
+
+* First-class link:caching.html[caching] support for enhanced application performance.
+
+* Built-in POJO-based Enterprise link:session-management-features.html[Session Management]. Use in both web and non-web environments or in any environment where Single Sign On (SSO) or clustered or distributed sessions are desired.
+
+* _Heterogeneous_ client session access. You are no longer forced to use only the <tt>httpSession</tt> or Stateful Session Beans, which often unnecessarily tie applications to specific environments. Flash applets, C# applications, Java Web Start, and Web Applications, etc. can now all share session state regardless of deployment environment.
+
+* Simple Single Sign-On (SSO) support piggybacking the above Enterprise Session Management. If sessions are federated across multiple applications, the user's authentication state can be shared too. Log in once to any application and the others all recognize that log-in.
+
+* Secure data with the easiest possible link:cryptography-features.html[Cryptography] APIs available, giving you power and simplicity beyond what Java provides by default for ciphers and hashes.
+
+* An incredibly robust yet _low-configuration_ web framework that can secure any url or resource, automatically handle logins and logouts, perform Remember Me services, and more.
+
+* Extremely low number of required dependencies. Standalone configuration requires only <tt>slf4j-api.jar</tt> and one of slf4j's binding .jars. Web configuration additionally requires <tt>commons-beanutils-core.jar</tt>. Feature-based dependencies (Ehcache caching, Quartz-based Session validation, Spring dependency injection, etc.) can be added when needed.
+
+== Want more information on what Shiro can do?
+
+Check out the specific features for each of Shiro's major components: link:authentication-features.html[Authentication], link:authorization-features.html[Authorization], link:session-management-features.html[Session Management], and link:cryptography-features.html[Cryptography].
+
+== Get Started in 10 Minutes with Shiro
+
+Try out Shiro for yourself with our link:10-minute-tutorial.html[10 Minute Tutorial]. And if you have any questions about Shiro, please check out our link:forums.html[community forum] or link:mailing-lists.html[user mailing list] for answers from the community.
diff --git a/how-to-contribute.md b/jbake/content/how-to-contribute.adoc
similarity index 54%
rename from how-to-contribute.md
rename to jbake/content/how-to-contribute.adoc
index 7562425..29aa566 100644
--- a/how-to-contribute.md
+++ b/jbake/content/how-to-contribute.adoc
@@ -1,19 +1,14 @@
-<a name="HowtoContribute-ContributingtoApacheShiro"></a>
-# Contributing to Apache Shiro
+= Contributing to Apache Shiro
+:jbake-type: page
+:jbake-status: published
+:jbake-tags: documentation, overview, features
+:idprefix:
+:icons: font
+:toc:
-* [Introduction](#HowtoContribute-introduction)
-* [Help Wanted Here](#HowtoContribute-help)
-* [Procedure for Raising Development Issues](#HowtoContribute-issues)
-* [Procedure for Reporting Bugs and Issues and Enhancement uggestions](#HowtoContribute-procedure)
-* [Git Usage](#HowtoContribute-git)
-* [Git Committers](#HowtoContribute-committer)
-* [Contribution Notes and Tips](#HowtoContribute-tips)
+== Introduction
-<a name="HowtoContribute-introductions"></a>
-<a name="HowtoContribute-Introduction"></a>
-## Introduction
-
-Apache Shiro is an [Open Source](https://opensource.org/) software security framework that performs authentication, authorization, cryptography and session management. The Shiro Project is an volunteer project released under a [liberal license](license.html "License"). Anyone can participate and volunteer. No need to be an experienced developer or have great visions. Roll up your sleeves and come try, help is always welcome, and your input will be appreciated!
+Apache Shiro is an https://opensource.org/[Open Source] software security framework that performs authentication, authorization, cryptography and session management. The Shiro Project is an volunteer project released under a link:license.html[liberal license]. Anyone can participate and volunteer. No need to be an experienced developer or have great visions. Roll up your sleeves and come try, help is always welcome, and your input will be appreciated!
There are many ways how to contribute to this project, you can participate directly by:
* coding
@@ -29,163 +24,159 @@ Or you can participate with resource donations:
* conference presentations
* publicity
* software
-* general hardware/money [donations](http://www.apache.org/foundation/thanks.html) via the [Apache Software Foundation](http://www.apache.org)
+* general hardware/money http://www.apache.org/foundation/thanks.html[donations] via the http://www.apache.org[Apache Software Foundation]
-You can get your local working copy of the [latest and greatest code](download.html "Download") by following the directions in [Download](download.html "Download") page. Review the To Do list in the [issue tracker](https://issues.apache.org/jira/browse/SHIRO) and then choose a task that interests you.
+You can get your local working copy of the link:download.html[latest and greatest code] by following the directions in link:download.html[Download] page. Review the To Do list in the https://issues.apache.org/jira/browse/SHIRO[issue tracker] and then choose a task that interests you.
-Perhaps you have noticed something that needs patching or have a new feature to contribute. Make the changes, do the testing, generate a patch, and discuss on the [dev mailing list](https://shiro.apache.org/mailing-lists.html "Mailing Lists"). The process is easy and explained below. Subscribe to the mailing list!
+Perhaps you have noticed something that needs patching or have a new feature to contribute. Make the changes, do the testing, generate a patch, and discuss on the https://shiro.apache.org/mailing-lists.html[dev mailing list]. The process is easy and explained below. Subscribe to the mailing list!
-<a name="HowtoContribute-help"></a>
-<a name="HowtoContribute-HelpWantedHere"></a>
-## Help Wanted
+== Help Wanted
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 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](#HowtoContribute-procedure)).
+* Debugging - producing reproducible test cases and/or finding causes of bugs. Most bugs are link:#procedure_for_raising_development_issues[recorded as issues].
* 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, analyzing or designing new features - and beyond.
-** If you wish to get further involved with this, please join the [`shiro-dev` mailing list](https://shiro.apache.org/mailing-lists.html "Mailing Lists"), install and try out Shiro and read some of the [mail archives](https://shiro.apache.org/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.
+** If you wish to get further involved with this, please join the https://shiro.apache.org/mailing-lists.html[`shiro-dev` mailing list], install and try out Shiro and read some of the https://shiro.apache.org/mailing-lists.html[mail archives].
+*** 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.
+* … 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
-If you think that you have found a bug or you have a suggestion for improvement, then please discuss it on one of the [mailing lists](https://shiro.apache.org/mailing-lists.html "Mailing Lists"). However, please check our [issue tracker](https://issues.apache.org/jira/browse/SHIRO) first as it may be already reported.
+If you think that you have found a bug, or you have a suggestion for improvement, then please discuss it on one of the https://shiro.apache.org/mailing-lists.html[mailing lists]. However, please check our https://issues.apache.org/jira/browse/SHIRO[issue tracker] first as it may be already reported.
-The [Apache Shiro Issue Tracker](https://issues.apache.org/jira/browse/SHIRO) collates our known issues. Obviously not every issue is listed there. Some issues have been discussed on the mailing list but do not yet have an issue recorded.
+The https://issues.apache.org/jira/browse/SHIRO[Apache Shiro Issue Tracker] collates our known issues. Obviously not every issue is listed there. Some issues have been discussed on the mailing list but do not yet have an issue recorded.
The Roadmap is the best way to get an overview. The Unscheduled list also needs regular review, and committers will schedule some of those for the next release.
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-issues"></a>
-<a name="HowtoContribute-ProcedureforRaisingDevelopmentIssues"></a>
-## Procedure for Raising Development Issues
+== 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.
-### Mailing List
+=== Mailing List
-Research your topic thoroughly before beginning to discuss a new development issue on the [mailing list](https://shiro.apache.org/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.
+Research your topic thoroughly before beginning to discuss a new development issue on the https://shiro.apache.org/mailing-lists.html[mailing list]. 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.
-### Issue Tracker
+=== Issue Tracker
-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.
+Experienced developers use the https://issues.apache.org/jira/browse/SHIRO[issue tracker] 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.
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.
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
While we encourage you to submit your contribution through GitHub pull requests, you can also attach a patch in a Jira ticket. For the purpose of these instructions, we'll assume that you already have a system with Git and have found a bug to fix or have a feature that you'd like to submit, and you're willing to contribute that code or documentation under the Apache License 2.0.
Further, if you're fixing a bug, we'll assume that you've either filed a bug report (where you will attach your patch) or are submitting a fix for a known bug. If you find a bug and would like to fix it, that's awesome! Please be sure to file the bug too, though.
-If you want to add a feature, you should bring it up for discussion on the dev@shiro.apache.org mailing list before implementing it. This ensures that it meshes with the plans that other contributors have for Apache Shiro, and that you're not doing redundant work. Other developers may also have ideas for the feature or suggestions that will help you land the feature without having to re-do the work. More information about our mailing lists can be found here.
+If you want to add a feature, you should bring it up for discussion on the link:mailto:dev@shiro.apache.org[dev@shiro.apache.org] mailing list before implementing it. This ensures that it meshes with the plans that other contributors have for Apache Shiro, and that you're not doing redundant work. Other developers may also have ideas [...]
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
+== Git Usage
-An overview of how to use Git to participate in Shiro development. Beginners, don'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 [...]
+An overview of how to use Git to participate in Shiro development. Beginners, don'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 link:download.html[Download Shiro] page explains how to check out the code base and build your local copy.
-<a name="HowtoContribute-gettingStartedGit"></a>
-### Getting Started with Development
+=== Getting Started with Development
-Go to [Github](https://github.com/apache/shiro "Shiro") and fork the project by pressing the Fork button. Fork makes a copy of an existing repository and you can start doing new development on your copy.
+Go to https://github.com/apache/shiro[GitHub] and fork the project by pressing the Fork button. Fork makes a copy of an existing repository and you can start doing new development on your copy.
-### Getting Started with Git
+=== Getting Started with Git
Add your name and email to your `~/.gitconfig`:
-``` bash
+[source,bash]
+----
$ git config --global user.name "Your Name"
$ git config --global user.email you@domain.com
-```
+
+----
Obtain a copy of the Shiro source code:
-``` bash
+[source,bash]
+----
$ git clone https://gitbox.apache.org/repos/asf/shiro.git
-```
+
+----
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
+[source,bash]
+----
$ git checkout -b mybranch
-```
+
+----
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
+[source,bash]
+----
[user@localhost shiro]$ git branch
main
* mybranch
-```
+----
Use `git add` to stage the changes. Commit the changes to your working branch:
-``` bash
+[source,bash]
+----
git commit -m "Insert a meaningful summary of changes here."
-```
+----
Finally, you can create a patch and attach it to the Jira issue:
-``` bash
+[source,bash]
+----
git format-patch main --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
-After 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 (dev@shiro.apache.org).
+=== Review
+
+After 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 (link:mailto:dev@shiro.apache.org)[dev@shiro.apache.org)].
-<a name="HowtoContribute-committer"></a>
-<a name="HowtoContribute-GitCommitters"></a>
-## Git Committers
+== Git Committers
-After a developer has consistently provided contributions such as code, documentation and discussion, and demonstrated commitment, 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).
+After a developer has consistently provided contributions such as code, documentation and discussion, and demonstrated commitment, then the rest of the dev community may vote to grant this developer commit access to the Git repository. See the http://www.apache.org/dev/[ASF developers resources] and especially the http://www.apache.org/dev/version-control.html[Source code repositories].
-<a name="HowtoContribute-patches"></a>
-<a name="HowtoContribute-Howtoprepareandcontributepatches"></a>
-## Contributing as a Non-Committer
+== 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).
+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 https://github.com/apache/shiro/blob/master/CONTRIBUTING.md[GitHub Contribution Guidelines].
-<a name="HowtoContribute-tips"></a>
-<a name="HowtoContribute-ContributionNotesandTips"></a>
-## Contribution Notes and Tips
+== Contribution Notes and Tips
This is a collection of tips for contributing to the project in a manner that is productive for all parties.
-### Links
-* [Tips for email contributors](http://www.apache.org/dev/contrib-email-tips.html).
-* Old questions and answers in [archives](https://shiro.apache.org/mailing-lists.html "Mailing Lists").
+=== Links
+
+* http://www.apache.org/dev/contrib-email-tips.html[Tips for email contributors].
+* Old questions and answers in https://shiro.apache.org/mailing-lists.html[archives].
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
+=== 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.
@@ -194,5 +185,4 @@ There are no dumb questions. But browse, search and learn from mailing list arch
** [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 utilize 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.
-<input type="hidden" id="ghEditPage" value="how-to-contribute.md"></input>
+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 utilize 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.