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/04/26 09:26:48 UTC
Documentation questions from a newcomer
Hello Camel developers,
I'm Karen Lease & I'm interested in contributing to your project. Many
years ago I was a committer on FOP but stopped due to my professional
workload. For my job I had developed a small "pipeline" project to chain
together various processes such as XSLT & FOP specified in an XML
configuration, so the Camel philosophy is familiar to me.
As suggested, I started by browsing the documentation (which is very
nicely presented) and I found a small issue on the User Stories page
which I propose to fix.
On the rendered page at
https://camel.apache.org/manual/latest/user-stories.html, the cells are
in the wrong column after the "Red Hat integration" link. This is due to
a missing vertical bar after the RedHat link in the file
https://github.com/apache/camel/blob/main/docs/user-manual/modules/ROOT/pages/user-stories.adoc.
As I'm a newbie to the project and also to Github, I'd like to confirm
how this should be fixed. If I click on the "Edit this page" link, it
says I have to fork the repository to propose changes. So I assume that
means I should:
1. Fork the camel repository
2. Commit the change in my fork
3. Submit a pull request to integrate the fork into the main repository
Is that correct? The reason I'm asking is that the description on the
page
https://camel.apache.org/manual/latest/faq/how-do-i-edit-the-website.html
doesn't say anything about the "forking" process and implies that after
clicking "Edit this page", you only need to edit the file, preview the
changes and that will automatically create the pull request. Making a
fork just to add one character seems like overkill but if that's the
process, I'm fine with it. In that case, I could also make some minor
changes to grammar which I noticed while browsing other docs.
I also noticed that the page "how-do-i-edit-the-website.html" has some
inconsistencies in the description of how to edit the documentation in a
local repository. For example, it says that the site.yml file should be
updated to reference your local repository, but there isn't such a file.
When I looked at the https://github.com/apache/camel-website repository,
I found it also contained a user-stores.md page
(https://github.com/apache/camel-website/blob/main/content/community/user-stories.md)
but with different content than the adoc file.
Since the actual website matches the adoc file, I assume the md file in
camel-website is obsolete. There are some other files which have both
.adoc & .md files. Would it make sense to delete the .md files from the
camel-website if those are obsolete?
Thanks in advance for any suggestions,
Karen
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
Re: Documentation questions from a newcomer
Posted by Karen Lease <ka...@gmail.com>.
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 Zoran Regvart <zo...@regvart.com>.
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
> 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
> 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.
> 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
--
Zoran Regvart
Re: Documentation questions from a newcomer
Posted by Karen Lease <ka...@gmail.com>.
Hi Zoran,
Thanks for your explanations about the editing process and the reason
for the duplicated adoc & md files.
I found that besides the user-stories files, there are a few other files
referenced in Community which are also duplicated. There are also some
slight inconsistencies in the links between the Community page linked
from top menu and the Community links in the page footers on the
generated site. I made the following table which shows the source files
and which one is used where. Hopefully the formatting will be clear in
the mail.
In the first column are the .adoc files in
camel/docs/user-manual/modules/ROOT/pages. In the second comun are the
.md files in camel-website/content in the community (comm) and docs
folders. The other columns show which file is referenced in which links.
The links in the User manual Nav menu are on the left. They are all
under the Community heading except Books & Building which are under
"Resources and Guides". The links in the "Main page" column are in
https://camel.apache.org/ in the section "Apache & Opensource".
It appears that the 2 md files in camel-website/content/docs are not
currently referenced in the generated site.
FILES | REFERENCES
-----------------------------------------------------------------------------------------------------------
user-manual .adoc | camel-website .md | User manual Nav | Top
menu/Community | Footer/Community | Main page
-----------------------------------------------------------------------------------------------------------
contributing | | adoc |
adoc | adoc | adoc
release-guide | | adoc |
- | - | -
mailing-lists | comm/mailing-list | adoc |
- | adoc | md
support | comm/support | adoc |
md | md | -
team | comm/team.md | adoc |
md | md | -
user-stories | comm/user-stores | adoc |
md | md | -
- | comm/articles | - |
md | md | -
books | comm/books | adoc |
md | md | -
- | comm/sources | - |
- | - | md
- | comm/camel-extra | - |
- | - | -
building | docs/building | adoc |
- | - | -
- | docs/sources | - |
- | - | -
Definitely it would be preferable to have only one copy of
mailing-lists, support, team, user-stories & books files. So if we
followed your idea and kept the .md files for those, then we would need to:
1. Compare & merge more recent changes from adoc files to md files and
remove the .adoc files.
2. Change links in the user manual navigation, assuming we want to
reference those pages in the user manual.
3. Change the footer link to mailing-list to reference the md page
instead of the adoc page.
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.
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.
What's your feedback on this plan?
Karen
On 27/04/2021 10:10, Zoran Regvart wrote:
> Hi Karen,
> thanks for taking interest in our project and especially around the
> documentation! Some answers inline.
>
> On Mon, Apr 26, 2021 at 10:54 PM Karen Lease <ka...@gmail.com> wrote:
>> Thanks for the reply.
>>
>> In fact, when I click the "Edit this page" link, it takes me to the git
>> repository page with this message:
>>
>> "You need to fork this repository to propose changes.
>> Sorry, you’re not able to edit this repository directly—you need to fork
>> it and propose your changes from there instead."
>>
>> I am connected with my github account but apparently that's not sufficient.
> Yes, this is the process, on GitHub contributions by way of pull
> requests can be done only from forks. Though clicking on "Fork this
> repository" should set everything up for you and you should be able to
> do edits from there and propose changes via pull requests. The preview
> is done only for the changes made to the apache/camel-website
> repository, for changes to other repositories (like apache/camel) we
> don't have the preview. After merging the changes, if there are no
> issues found by checks the website is updated in the next 20-30min.
>
>>>> Since the actual website matches the adoc file, I assume the md file in
>>>> camel-website is obsolete. There are some other files which have both
>>>> .adoc & .md files. Would it make sense to delete the .md files from the
>>>> camel-website if those are obsolete?
> We started with content from the previous system (Confluence Wiki),
> and in the process of conversion sometimes we duplicated the effort
> and ended up with copies. The website gathers content from multiple
> repositories (and branches) and formats (asciidoc and markdown). We
> never took the time to implement a documentation strategy, as to where
> what kind of content is placed. For me it would make more sense to
> have the user stories outside of the user manual, that is in the
> markdown file. That ends up being published here:
>
> https://camel.apache.org/community/user-stories/
>
> And that's the version we link from the community page
> (https://camel.apache.org/community/).
>
> If that makes sense to folk, it seems that we need to refresh that
> markdown file with the changes that went into the asciidoc file in the
> user manual and consider removing that copy.
>
> zoran
Re: Documentation questions from a newcomer
Posted by Zoran Regvart <zo...@regvart.com>.
Hi Karen,
thanks for taking interest in our project and especially around the
documentation! Some answers inline.
On Mon, Apr 26, 2021 at 10:54 PM Karen Lease <ka...@gmail.com> wrote:
>
> Thanks for the reply.
>
> In fact, when I click the "Edit this page" link, it takes me to the git
> repository page with this message:
>
> "You need to fork this repository to propose changes.
> Sorry, you’re not able to edit this repository directly—you need to fork
> it and propose your changes from there instead."
>
> I am connected with my github account but apparently that's not sufficient.
Yes, this is the process, on GitHub contributions by way of pull
requests can be done only from forks. Though clicking on "Fork this
repository" should set everything up for you and you should be able to
do edits from there and propose changes via pull requests. The preview
is done only for the changes made to the apache/camel-website
repository, for changes to other repositories (like apache/camel) we
don't have the preview. After merging the changes, if there are no
issues found by checks the website is updated in the next 20-30min.
> >> Since the actual website matches the adoc file, I assume the md file in
> >> camel-website is obsolete. There are some other files which have both
> >> .adoc & .md files. Would it make sense to delete the .md files from the
> >> camel-website if those are obsolete?
We started with content from the previous system (Confluence Wiki),
and in the process of conversion sometimes we duplicated the effort
and ended up with copies. The website gathers content from multiple
repositories (and branches) and formats (asciidoc and markdown). We
never took the time to implement a documentation strategy, as to where
what kind of content is placed. For me it would make more sense to
have the user stories outside of the user manual, that is in the
markdown file. That ends up being published here:
https://camel.apache.org/community/user-stories/
And that's the version we link from the community page
(https://camel.apache.org/community/).
If that makes sense to folk, it seems that we need to refresh that
markdown file with the changes that went into the asciidoc file in the
user manual and consider removing that copy.
zoran
--
Zoran Regvart
Re: Documentation questions from a newcomer
Posted by Karen Lease <ka...@gmail.com>.
Thanks for the reply.
In fact, when I click the "Edit this page" link, it takes me to the git
repository page with this message:
"You need to fork this repository to propose changes.
Sorry, you’re not able to edit this repository directly—you need to fork
it and propose your changes from there instead."
I am connected with my github account but apparently that's not sufficient.
On 26/04/2021 22:37, Andrea wrote:
> Welcome!
>
> answers inline:
>
> On Mon, Apr 26, 2021, at 11:26, Karen Lease wrote:
>> Hello Camel developers,
>>
>> I'm Karen Lease & I'm interested in contributing to your project. Many
>> years ago I was a committer on FOP but stopped due to my professional
>> workload. For my job I had developed a small "pipeline" project to chain
>> together various processes such as XSLT & FOP specified in an XML
>> configuration, so the Camel philosophy is familiar to me.
>>
>> As suggested, I started by browsing the documentation (which is very
>> nicely presented) and I found a small issue on the User Stories page
>> which I propose to fix.
>>
>> On the rendered page at
>> https://camel.apache.org/manual/latest/user-stories.html, the cells are
>> in the wrong column after the "Red Hat integration" link. This is due to
>> a missing vertical bar after the RedHat link in the file
>> https://github.com/apache/camel/blob/main/docs/user-manual/modules/ROOT/pages/user-stories.adoc.
>>
>> As I'm a newbie to the project and also to Github, I'd like to confirm
>> how this should be fixed. If I click on the "Edit this page" link, it
>> says I have to fork the repository to propose changes. So I assume that
>> means I should:
>>
>> 1. Fork the camel repository
>>
>> 2. Commit the change in my fork
>>
>> 3. Submit a pull request to integrate the fork into the main repository
> This is the general process for contributing used for multi file contribution more complicated contribution.
>
>> Is that correct? The reason I'm asking is that the description on the
>> page
>> https://camel.apache.org/manual/latest/faq/how-do-i-edit-the-website.html
>> doesn't say anything about the "forking" process and implies that after
>> clicking "Edit this page", you only need to edit the file, preview the
>> changes and that will automatically create the pull request. Making a
>> fork just to add one character seems like overkill but if that's the
>> process, I'm fine with it. In that case, I could also make some minor
>> changes to grammar which I noticed while browsing other docs.
> For smaller fixes is totally fine to just use the "Edit this page button".
>
>> I also noticed that the page "how-do-i-edit-the-website.html" has some
>> inconsistencies in the description of how to edit the documentation in a
>> local repository. For example, it says that the site.yml file should be
>> updated to reference your local repository, but there isn't such a file.
>> When I looked at the https://github.com/apache/camel-website repository,
>> I found it also contained a user-stores.md page
>> (https://github.com/apache/camel-website/blob/main/content/community/user-stories.md)
>> but with different content than the adoc file.
>>
>> Since the actual website matches the adoc file, I assume the md file in
>> camel-website is obsolete. There are some other files which have both
>> .adoc & .md files. Would it make sense to delete the .md files from the
>> camel-website if those are obsolete?
> Not sure here cc: zoran@regvart.com
>
>> Thanks in advance for any suggestions,
>>
>> Karen
>>
>>
>>
>>
Re: Documentation questions from a newcomer
Posted by Andrea <an...@tarocch.it>.
Welcome!
answers inline:
On Mon, Apr 26, 2021, at 11:26, Karen Lease wrote:
> Hello Camel developers,
>
> I'm Karen Lease & I'm interested in contributing to your project. Many
> years ago I was a committer on FOP but stopped due to my professional
> workload. For my job I had developed a small "pipeline" project to chain
> together various processes such as XSLT & FOP specified in an XML
> configuration, so the Camel philosophy is familiar to me.
>
> As suggested, I started by browsing the documentation (which is very
> nicely presented) and I found a small issue on the User Stories page
> which I propose to fix.
>
> On the rendered page at
> https://camel.apache.org/manual/latest/user-stories.html, the cells are
> in the wrong column after the "Red Hat integration" link. This is due to
> a missing vertical bar after the RedHat link in the file
> https://github.com/apache/camel/blob/main/docs/user-manual/modules/ROOT/pages/user-stories.adoc.
>
> As I'm a newbie to the project and also to Github, I'd like to confirm
> how this should be fixed. If I click on the "Edit this page" link, it
> says I have to fork the repository to propose changes. So I assume that
> means I should:
>
> 1. Fork the camel repository
>
> 2. Commit the change in my fork
>
> 3. Submit a pull request to integrate the fork into the main repository
This is the general process for contributing used for multi file contribution more complicated contribution.
> Is that correct? The reason I'm asking is that the description on the
> page
> https://camel.apache.org/manual/latest/faq/how-do-i-edit-the-website.html
> doesn't say anything about the "forking" process and implies that after
> clicking "Edit this page", you only need to edit the file, preview the
> changes and that will automatically create the pull request. Making a
> fork just to add one character seems like overkill but if that's the
> process, I'm fine with it. In that case, I could also make some minor
> changes to grammar which I noticed while browsing other docs.
For smaller fixes is totally fine to just use the "Edit this page button".
> I also noticed that the page "how-do-i-edit-the-website.html" has some
> inconsistencies in the description of how to edit the documentation in a
> local repository. For example, it says that the site.yml file should be
> updated to reference your local repository, but there isn't such a file.
> When I looked at the https://github.com/apache/camel-website repository,
> I found it also contained a user-stores.md page
> (https://github.com/apache/camel-website/blob/main/content/community/user-stories.md)
> but with different content than the adoc file.
>
> Since the actual website matches the adoc file, I assume the md file in
> camel-website is obsolete. There are some other files which have both
> .adoc & .md files. Would it make sense to delete the .md files from the
> camel-website if those are obsolete?
Not sure here cc: zoran@regvart.com
> Thanks in advance for any suggestions,
>
> Karen
>
>
>
>