Hi Zoran,
On 06/05/2021 07:31, Zoran Regvart wrote:
Hi Karen,
replying to two emails with one :)
...
This is a very interesting approach, and I do like it, we get to
maintain one copy, which I really like.
I wonder, though, we have several contribution documents, one per
subproject (see below). Perhaps it would make more sense to have
/CONTRIBUTING.md per repository and point to the website section with
a contribution guide for each subproject (and perhaps to the user
manual section, that seems broader).
This is what I found on the asf-site branch:
https://camel.apache.org/camel-quarkus/latest/contributor-guide/
https://camel.apache.org/manual/latest/contributing.html
https://camel.apache.org/camel-k/latest/contributing
https://camel.apache.org/camel-kafka-connector/[latest,0.4.x,0.7.x]/contributing.html
zoran
Just when I thought I had it worked out, you added some new information -:)
I had to cogitate a while on this and look at what was in these docs
currently, and where it was referenced (usually in the README.md or
README.adoc in the repositories.)
I agree with your suggestion, and here is how I propose to refactor the
current content:
1. The CONTRIBUTING.md in each camel-xxx github repository would be
quite short and cover the points directly related to making a github
issue or pull request, since that's where it's automatically referenced.
- How to fork & clone the repo
- How to build (e.g. mvn ...)
- Reminder to write a unit test with assertions
- Reminder to run checkstyle
- Reminder to update documentation if needed
- Link to more general guidelines for camel newcomers
(camel.apache.org/community/contributing)
- Link to more specific technical information about contributing in
website user manual page (links you mention above)
2. The main community/contributing would contain most of the
introductory information from the current github/camel/CONTRIBUTING.md &
the user manual/contributing.adoc file. It would cover the introductory
information & suggestions for getting involved, mailing lists, chat,
using JIRA (or github issues for some of the subprojects), submitting a
patch if not using a pull request, becoming a committer.
3. Leave the contributing.html pages in the sub-projects which you
mention above as they are.
4. Replace the "Community" section in the main camel user manual with a
Contributor section, similar to the one in camel-quarkus. This would
contain the current "Release guide" page and some of the information in
the current "Contributing" manual page such as "Testing the changes",
"Verify Karaf reatures", which would not be put in the
Community/Contributing page. I think it would be worth putting the
"Improving the documentation" in its own page in that section.
By the way, is there some reason why JIRA is used for the main Camel
project, and also for Camel-Karaf & Spring boot, but the GitHub issues
list is used for Camel-K, Kafka & Quarkus?
Karen
