Docs contribution section #25374
Docs contribution section #25374
Conversation
spring-projects-issues
added
the
status: waiting-for-triage
|
|
||
| The documentation is stored in this repository, in the link:https://github.com/spring-projects/spring-boot/tree/master/spring-boot-project/spring-boot-docs/src/docs/asciidoc[spring-boot-docs] project. | ||
|
|
||
| You may use GitHub's built-in editor for Asciidoc by pressing the top-right Edit button to edit the documentation in browser. |
There was a problem hiding this comment.
I am not sure we should bother describing the various ways changes can be contributed on GitHub. As a matter of a fact, I prefer contributions that originate from "real branches" as it makes the follow-up easier. We expect contributors to build the documentation and check that the output is valid which you cant' do using the web editor.
There was a problem hiding this comment.
Aren't there automatic checks (doc build) on a PR request even when using the github's web editor?
There was a problem hiding this comment.
A contributor is expected to validate their changes before submitting a PR and I am not keen to let contributors use our CI infrastructure to validate their changes.
Part of that is because if you keep this trial and error until you push something that works, you'd trigger a notification for each commit attempt to the 3K people watching this repository.
Having said that, I can see how simple documentation changes could be easily validated from your browser.
| The documentation is stored in this repository, in the link:https://github.com/spring-projects/spring-boot/tree/master/spring-boot-project/spring-boot-docs/src/docs/asciidoc[spring-boot-docs] project. | ||
|
|
||
| You may use GitHub's built-in editor for Asciidoc by pressing the top-right Edit button to edit the documentation in browser. | ||
| Alternatively, you can clone and change it in an editor of your choice on your machine. |
There was a problem hiding this comment.
I am not sure what that sentence brings to this section.
snicoll
added
the
status: waiting-for-feedback
|
Contribution section needs a guide to editing docs (#23726 (comment)), to answer questions like:
|
snicoll
added
the
for: team-attention
spring-projects-issues
added
status: feedback-provided
|
I saw that but I am not sure why we should create a dedicated section for this. Flagging for team attention to get some more feedback. |
|
To me, the documentation is part of the project's code. I think a subsection in the "Working with the Code" section, describing where the documentation lives and noting that it's written in Asciidoc, would be a good addition. |
philwebb
added
for: merge-with-amendments
No description provided.