We should use include-code for all samples within the documentation. This will allow us to test the sample code to ensure that it works.

If you are wanting to contribute to this issue, please:

  • Select a single adoc page that you will work on
  • Check to see that it isn't already being worked on
  • Comment on this ticket that you will be working on it
  • Submit a pull request to the 6.5.x branch with the changes using https://github.com/spring-projects/spring-security/commit/6eee256e12663a5465be6fceffe0b75178f23c37 as a guide to how to make the changes
  • However, please make the changes to the entire adoc page in a single commit / PR.
  • Before submitting the pull request, please diff the html page that is generated by ./gradlew antora before and after your changes
  • Consider adding tests if it makes sense

Comment From: christophsj

Hi! I am a spring security user and I would love to contribute.

However, I do not seem to be able to create a sub issue. I am a first time contributor, is this expected?

Comment From: jkuhel

Hi @rwinch

I would like to help on this issue if it is still available to work on.

To get started, I did attempt to create a sub-issue to work on docs/modules/ROOT/pages/servlet/test/method.adoc. However, I was not able to because it looks like only accounts with at least triage permissions for a given repository can create sub-issues. I'd be glad to create sub-issues if my account has permissions. Let me know what's best.

In the mean time, I followed your example and made changes to the above page to use include-code and added some tests. For the time being, I opened this PR to the 6.5.x branch to start with. Please let me know if this helpful and on the right track.

If everything looks good here as a starting point, I can recreate the branch and PR once a sub-issue is created and link the commit/PR accordingly.

I can also take on the updates to additional pages and happy to collaborate/divide up the pages with others (like @christophsj).

Comment From: rwinch

@christophsj @jkuhel Thanks for the feedback. I've updated the instructions so that to claim a file you should just post it as a comment on this ticket. Then the PR should be linked to this ticket.

Also note that I added a recommendation to perform a diff on the before and after on the html page that is generated.

Comment From: jkuhel

Thanks @rwinch! I'm getting started on docs/modules/ROOT/pages/servlet/architecture.adoc

Comment From: himanshu-pareek

Hi @rwinch , I am getting started on docs/modules/ROOT/pages/features/authentication/password-storage.adoc.

Comment From: himanshu-pareek

Hi @rwinch , I am getting started on docs/modules/ROOT/pages/features/authentication/password-storage.adoc.

@rwinch , I was working on this and I have few queries: 1. Diff of the older html file with the new html file shows 2 differences for each of the change made: First, for each java code-block, the primary css class is deleted and for each kotlin code-block, the secondary css class is deleted as shown in the screenshots. This does not have any visual impact on the ui, btw:

Image Image

Second, there are some whitespace changes, since the code written in java or kotline files have different formatting (see the screenshot below). Please suggest what to do in this case.

Image

  1. What needs to be done with the code samples, where xml tab is also present along with java and kotlin. I did not find any include-code configuration for xml. Should we leave those as it is or add configuration for include-xml?
  2. I have found a minor mistake in the example code blocks given (1 incorrect parameter name). Should I fix that as part of this change or create new issue / PR?

Comment From: himanshu-pareek

Hi @rwinch , I am getting started on docs/modules/ROOT/pages/features/authentication/password-storage.adoc.

@rwinch , I was working on this and I have few queries:

  1. Diff of the older html file with the new html file shows 2 differences for each of the change made: First, for each java code-block, the primary css class is deleted and for each kotlin code-block, the secondary css class is deleted as shown in the screenshots. This does not have any visual impact on the ui, btw:

Second, there are some whitespace changes, since the code written in java or kotline files have different formatting (see the screenshot below). Please suggest what to do in this case.

2. What needs to be done with the code samples, where xml tab is also present along with java and kotlin. I did not find any include-code configuration for xml. Should we leave those as it is or add configuration for include-xml? 3. I have found a minor mistake in the example code blocks given (1 incorrect parameter name). Should I fix that as part of this change or create new issue / PR?

@rwinch I will go ahead with the following steps and will raise a PR: 1. I will ignore the diff which is not significant for the UI. 2. I won't touch the code samples where xml is present. 3. I will fix the minor error in the documentation.