spring-projects / spring-projects/spring-security
Update documentation of sample apps
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 9.6k
- Forks
- 6.3k
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 52
Description
Chapter 7 Samples is quite lite on content, it just links to the samples directory on git repo. I propose adding the following sections to the Samples chapter.
- A short overview section describing what samples exist in the samples/ project
- Sample apps directory with an entry for each sample app.
This would have an entry for each sample app should include
- a short 1 to 3 sentence description of what the sample app demonstrates, so that users can quickly find an example of what they are looking to do.
- a link to the sample application source code to easily find the code
The samples directory can be nicely organized along into category to make discovery easier. Suggested categories are.
- Servlets
- Web Authentication
- Web Authorization
- Method Security
- Reactive
- Web Authentication
- Web Authorization
- Method Security
It is possible to generate the content for such a directory automatically, below are some approaches.
buildfile approach Each samples gradle build file can define a gradle task to write out an summary.adoc file, then the parent project can iterate the child projects call each of the generate summary tasks, and collect all the output into the summary chapter. With this approach as the samples are updated summary directory gets generated.
description.md approach each samples gets a new file called description.md or description.adoc that can be included from the samples chapter.
The build file approach can more easily tag and category the samples, and potentially can be leveraged to drop references to sample apps in different sections of the docs.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Chapter 7 Samples documentation and the samples/ project referenced in the issue. Review the sample applications and their Gradle build files, then choose between generated summary.adoc files and per-sample description.md or description.adoc files. Done means the Samples chapter has an overview, categorized entries, descriptions, and source links for each sample.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100