You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@camel.apache.org by Karen Lease <ka...@gmail.com> on 2021/05/04 15:12:48 UTC
Re: Documentation questions from a newcomer
Hi Zoran,
Thanks for the approval & useful feedback.
I've made the changes as discussed below and pushed them to my forked
repositories for camel & camel-website (https://github.com/klease/camel
& https://github.com/klease/camel-website/). The changes from the main
repo are also merged & pushed to my fork; not sure that was necessary or
not.
I added some more detail inline below about the changes I made.
Running "yarn preview" and viewing the generated site locally looks
good, as well as the link check.
Before creating the pull requests I have a few more questions.
1. There is no contributing.md file in the camel-website/community
content but there is both a CONTRIBUTING.md file at the root of the
camel repository as well as the file
docs/user-manual/modules/ROOT/pages/contributing.adoc. All the
contributing links in the website reference the HTML file generated from
the .adoc file. The camel/README.md file references CONTRIBUTING.md.
These files are similar but not identical and both have been modified
recently. Would it make sense to also move the contributing.md file to
the community content & reference that one from everywhere, including
the main README?
2. The camel/REAMDE.md has links to mailing-list and support pages which
are just http://camel.apache.org/support.html but end up on the
generated HTML pages in the user-manual so they'll be broken. I assume
it needs to be changed to https://camel.apache.org/community/support/?
3. When running "yarn preview" I hit the limit of unauthenticated API
requests on github to get the issues when building the release notes.
This gives errors like this "ERROR 2021/05/04 15:34:06 Failed to get
JSON resource
"https://api.github.com/repos/apache/camel-k-runtime/issues?state=closed&milestone=10":
Failed to retrieve remote file: Forbidden". Waiting a while and trying
again allows it to finish. There doesn't seem to be any way to
authenticate on the getJSON request in the Hugo template. It might be
worth mentioning it in the doc about building the website locally :)
Cheers,
Karen
On 29/04/2021 10:41, Zoran Regvart wrote:
> Hi Karen,
> thank you for doing the analysis and for the very thoughtful plan.
> Replies are inline.
>
> On Wed, Apr 28, 2021 at 11:56 AM Karen Lease <ka...@gmail.com> wrote:
> [snip]
>> 1. Compare & merge more recent changes from adoc files to md files and
>> remove the .adoc files.
> +1, I prefer the manual to be focused on using Camel, and the
> community bits outside of the manual
>
KL: Done, main changes were in the user-stories and team lists. I also
added the Nabble links to the mailing-list page.
>> 2. Change links in the user manual navigation, assuming we want to
>> reference those pages in the user manual.
> +1, I think, since we have the top menu for Community we can also
> remove these from the manual. Those are in
> docs/user-manual/modules/ROOT/nav.adoc of the apache/camel repository
> on GitHub
KL: In the nav.adoc files, I left the links Resources & Guides/Books
and the Community links which I didn't move (Contributing, Release
guide, Chat room) as well as FAQ/How can I get help? which directly
points to the support page. I used "link:/community/xxx/" which works in
preview mode. Using a relative link like ../../comunity/xxx in the
nav.adoc files doesn't work because it's included at different levels
(user-manual & user-manual/faq.) I suppose these could be completely
removed instead, especially if we also move the "Contributing" page to
community.
>> 3. Change the footer link to mailing-list to reference the md page
>> instead of the adoc page.
> +1, two changes are needed, due to using Antora and Hugo to build the
> website we have two sets of templates, in:
> antora-ui-camel/src/partials/footer-content.hbs and
> layouts/partials/footer.html of the apache/camel-website repository on
> GitHub
>
>> 4. Possibly add a Mailing List section to the main Community page to be
>> consistent with the Footer link. It is linked from the Support page already.
> +1, folk often miss the mailing list I think, this would help more
> folk in finding it.
KL: I added it; for now it has the same icon as the Support link
>> 5. Check and fix embedded links to the user manual pages which would be
>> replaced with the pages generated from the .md files. As far as I can
>> tell, there aren't too many.
> +1, we have a link checker in the website run with `yarn check:links`,
> it'll check all site relative links, and another checker (run with
> yarn check:html) forbids links to camel.apache.org that are not site
> relative. I suspect there might be a fair bit of xref links to the
> community from the user manual or perhaps from components or sub
> projects as well. Hopefully the checks will catch them all.
>
>> What's your feedback on this plan?
> Sounds like you have a very clear understanding of what we need fixed.
> Please do reach out if you find any issues or need any help with this.
>
> Thanks!
>
> zoran
Re: Documentation questions from a newcomer
Posted by Karen Lease <ka...@gmail.com>.
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
Re: Documentation questions from a newcomer
Posted by Karen Lease <ka...@gmail.com>.
Hi Camel developers,
I've committed the refactoring of the community pages in the Camel
website (see CAMEL-16576 in JIRA) and created 2 pull requests, one for
the main camel repository and one for the camel-website repository.
Many thanks to Zoran for his support & advice. Hopefully, I've managed
to follow the contribution guidelines in the pages I've moved & edited!
Karen Lease
Re: Documentation questions from a newcomer
Posted by Zoran Regvart <zo...@regvart.com>.
Hi Karen,
replying to two emails with one :)
On Wed, May 5, 2021 at 7:41 PM Karen Lease <ka...@gmail.com> wrote:
> Footnotes in a mail--I'm impressed! Thanks again for the excellent
> mentoring.
:) thank you for taking the time to discuss changes, and being very thorough!
> Everything is clear except the contributing.md which is still a bit
> fuzzy for me.
>
> I now understand why there should be a CONTRIBUTING.md at the root of
> the repository, but when you say "and just point to the website from
> there", I'm not sure what you mean. Do you mean having a minimum
> CONTRIBUTING.md file at the root which just links to
> community/contributing.md which has the full content?
My initial thought was to have a link in the /CONTRIBUTING.md to the
website (camel.apache.org/comminity/...), i.e. from the Hugo bit, not
the manual
On Wed, May 5, 2021 at 11:43 PM Karen Lease <ka...@gmail.com> wrote:
>
> Hi Zoran (and all)
>
> In my previous mail I wrote:
>
> >>The ideal would perhaps be to include the CONTRIBUTING.md
> automatically in the website when it's built, but I haven't delved into
> the generator tools enough to know if that's doable. Also there would be
> some differences with links, since the ones in the repository version
> link with absolute URLs to the website.
>
> So I delved into it and found a working solution:
>
> In the MD file for the generated website
> (content/community/contributing.md), use a "shortcode" with the URL of
> the github CONTRIBUTING.md:
>
> {{< includefile
> file="https://api.github.com/repos/apache/camel/contents/CONTRIBUTING.md"
> >}}
>
> and define the shortcode includefile.html like this:
>
> {{ $response := getJSON (.Get "file") }}
> {{ $response.content | base64Decode | replaceRE
> "https://camel.apache.org/manual" "/manual" | markdownify }}
>
> Does this seem like a workable plan?
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
--
Zoran Regvart
Fwd: Documentation questions from a newcomer
Posted by Karen Lease <ka...@gmail.com>.
Hi Zoran (and all)
In my previous mail I wrote:
>>The ideal would perhaps be to include the CONTRIBUTING.md
automatically in the website when it's built, but I haven't delved into
the generator tools enough to know if that's doable. Also there would be
some differences with links, since the ones in the repository version
link with absolute URLs to the website.
So I delved into it and found a working solution:
In the MD file for the generated website
(content/community/contributing.md), use a "shortcode" with the URL of
the github CONTRIBUTING.md:
{{< includefile
file="https://api.github.com/repos/apache/camel/contents/CONTRIBUTING.md"
>}}
and define the shortcode includefile.html like this:
{{ $response := getJSON (.Get "file") }}
{{ $response.content | base64Decode | replaceRE
"https://camel.apache.org/manual" "/manual" | markdownify }}
Does this seem like a workable plan?
Karen
Re: Documentation questions from a newcomer
Posted by Karen Lease <ka...@gmail.com>.
Hi Zoran,
Footnotes in a mail--I'm impressed! Thanks again for the excellent
mentoring.
Everything is clear except the contributing.md which is still a bit
fuzzy for me.
I now understand why there should be a CONTRIBUTING.md at the root of
the repository, but when you say "and just point to the website from
there", I'm not sure what you mean. Do you mean having a minimum
CONTRIBUTING.md file at the root which just links to
community/contributing.md which has the full content?
Linking from the website to the github CONTRIBUTING.md would require
using an absolute URL which doesn't feel right. If we keep the full
content in both places, we'll surely get them out of sync again.
The ideal would perhaps be to include the CONTRIBUTING.md automatically
in the website when it's built, but I haven't delved into the generator
tools enough to know if that's doable. Also there would be some
differences with links, since the ones in the repository version link
with absolute URLs to the website.
Since the changes are considerably larger than the initial idea of just
changing user-stories, I created a JIRA ticket:
https://issues.apache.org/jira/browse/CAMEL-16576; maybe you could
assign it to me? I noticed there are a few other website issues already
in JIRA, including CAMEL-14567 which seems to have been done.
Karen Lease
On 05/05/2021 11:43, Zoran Regvart wrote:
> Hi Karen,
>
> .....
> Before creating the pull requests I have a few more questions.
>
> 1. There is no contributing.md file in the camel-website/community
> content but there is both a CONTRIBUTING.md file at the root of the
> camel repository as well as the file
> docs/user-manual/modules/ROOT/pages/contributing.adoc. All the
> contributing links in the website reference the HTML file generated from
> the .adoc file. The camel/README.md file references CONTRIBUTING.md.
> These files are similar but not identical and both have been modified
> recently. Would it make sense to also move the contributing.md file to
> the community content & reference that one from everywhere, including
> the main README?
> I think that makes sense, I'd keep the CONTRIBUTING.md file at the
> root of repositories and just point to the website from there. The
> reason behind having a CONTRIBUTING.md is that it became a sort of
> convention for open source projects on GitHub, to a degree where it's
> now part of the of the UI on GitHub[2]
>
>
> --
> Zoran Regvart
Re: Documentation questions from a newcomer
Posted by Zoran Regvart <zo...@regvart.com>.
Hi Karen,
On Tue, May 4, 2021 at 5:13 PM Karen Lease <ka...@gmail.com> wrote:
> I've made the changes as discussed below and pushed them to my forked
> repositories for camel & camel-website (https://github.com/klease/camel
> & https://github.com/klease/camel-website/). The changes from the main
> repo are also merged & pushed to my fork; not sure that was necessary or
> not.
This looks good to me, I've added a comment on GitHub to a commit in
your fork about pointing the mailing list archives to
lists.apache.org, i.e. for the users mailing list to point to
https://lists.apache.org/list.html?users@camel.apache.org. Also, we
don't need to point to Nabble any more, there was a spam concern
(discussed on private@ in June of 2017) where we decided not to point
folk to Nabble any more.
> Running "yarn preview" and viewing the generated site locally looks
> good, as well as the link check.
Perfect, one thing that you might have missed is that to speed up the
development some build steps and checks are disabled by default, to
get a full build and all the checks you can set the environment
variable `CAMEL_ENV=production`, there is a blurb on this in the
README[1]. You can do this if you want a near production build, though
all of this is run when a pull request is created so it's not
obligatory.
>
> Before creating the pull requests I have a few more questions.
>
> 1. There is no contributing.md file in the camel-website/community
> content but there is both a CONTRIBUTING.md file at the root of the
> camel repository as well as the file
> docs/user-manual/modules/ROOT/pages/contributing.adoc. All the
> contributing links in the website reference the HTML file generated from
> the .adoc file. The camel/README.md file references CONTRIBUTING.md.
> These files are similar but not identical and both have been modified
> recently. Would it make sense to also move the contributing.md file to
> the community content & reference that one from everywhere, including
> the main README?
I think that makes sense, I'd keep the CONTRIBUTING.md file at the
root of repositories and just point to the website from there. The
reason behind having a CONTRIBUTING.md is that it became a sort of
convention for open source projects on GitHub, to a degree where it's
now part of the of the UI on GitHub[2]
> 2. The camel/REAMDE.md has links to mailing-list and support pages which
> are just http://camel.apache.org/support.html but end up on the
> generated HTML pages in the user-manual so they'll be broken. I assume
> it needs to be changed to https://camel.apache.org/community/support/?
Yes, I think we need to be consistent here and have one URL to point folk to.
> 3. When running "yarn preview" I hit the limit of unauthenticated API
> requests on github to get the issues when building the release notes.
> This gives errors like this "ERROR 2021/05/04 15:34:06 Failed to get
> JSON resource
> "https://api.github.com/repos/apache/camel-k-runtime/issues?state=closed&milestone=10":
> Failed to retrieve remote file: Forbidden". Waiting a while and trying
> again allows it to finish. There doesn't seem to be any way to
> authenticate on the getJSON request in the Hugo template. It might be
> worth mentioning it in the doc about building the website locally :)
Yes, this is a known limitation, GitHub removed support for providing
authentication tokens via URL parameters and the HTTP calls from Hugo
can't include HTTP headers[4]. We get around that with caches, i.e.
for Hugo `HUGO_CACHEDIR` can be set to a filesystem path that stores
the caches. On ASF Jenkins we keep the cache, and for the checks
running on GitHub I think we get higher API limits (or so it seems).
And yes, it's definitely worth mentioning that in the README, I was
hoping that custom headers in HTTP calls would land soon in Hugo so I
didn't invest time in an alternative to getJSON. I think a pragmatic
course of action would be to wait for this to get supported in Hugo
until we see issues in publishing the website.
Looking forward to the pull request :)
zoran
[1] https://github.com/apache/camel-website/#camel_env-environment-variable
[2] https://github.blog/2012-09-17-contributing-guidelines/
[3] https://developer.github.com/changes/2019-11-05-deprecated-passwords-and-authorizations-api/#authenticating-using-query-parameters
[4] https://github.com/gohugoio/hugo/issues/5617
--
Zoran Regvart