You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@pulsar.apache.org by Yunze Xu <yz...@streamnative.io.INVALID> on 2022/10/04 14:20:52 UTC
[Discussion] Questions about the pulsar-site management
TL; DR, we should add the Markdown documents about the pulsar-site repo
in GitHub. DON'T USE GOOGLEDOCS EVERYWHERE!
----
Currently Pulsar's website is maintained in
https://github.com/apache/pulsar-site. However, I cannot find any
document of this document repo.
As a contributor, if I want to contribute to this repo, I will look at
the README first:
https://github.com/apache/pulsar-site/blob/main/README.md
However, I can barely find what I concerns about in it:
- Where should I add the content
- What should I do before opening a PR (e.g. building a preview)
- How can I build a preview in my local env
- How will the web page be updated due to the changes of this repo
If I were a frontend engineer, I might also want to know how to
develop the website for it.
What I can find is:
[Preview Website
Changes](https://docs.google.com/document/d/1wszdtMRo6MhKbVaggPK7_bnKaC4TewuT--GWZZxJNGg/edit#heading=h.wu6ygjne8e35)
from
https://github.com/apache/pulsar-site/tree/main/site2/website-next.
Yeah, I believe nobody will click into this directory if he cannot
find anything from the README.md in the root directory.
BTW, the details are in the external GoogleDocs link in https://github.com/apache/pulsar#documentation-1
There is a terrible case recently:
How to add the release note also changed after
https://github.com/apache/pulsar-site/pull/227, we need to update them
in JavaScript files. However, in
https://github.com/apache/pulsar/blob/master/wiki/release/release-process.md#write-release-notes,
there is no update in [Pulsar Release Notes
Guide](https://docs.google.com/document/d/1cwNkBefKyV6OPbEXnUrcCdVZi0i2BezqL6vAL7VqVC0/edit#).
If the release manager wants to know how to contribute the release
notes, he might tend to find a previous PR like
https://github.com/apache/pulsar-site/pull/209. Unfortunately, it's
outdated. We have to update the `.js` files now, e.g.
https://github.com/apache/pulsar-site/pull/242
IMO, we should add a guidance into the pulsar-site repo. In addition,
the documents should be maintained in GitHub as much as possible. It's
better not just pasting an external GoogleDocs link. We can use
GoogleDocs for the temporary changes, but we should present a stable
Markdown document in GitHub.
Thanks,
Yunze
Re: [Discussion] Questions about the pulsar-site management
Posted by Yunze Xu <yz...@streamnative.io.INVALID>.
Hi Yu,
Thank you for the explanation!
Yunze
On Mon, Oct 10, 2022 at 2:09 PM Yu <li...@apache.org> wrote:
>
> Hi Yunze,
>
> Thanks for your feedback!
>
> We (@SignorMercurio, @urfreespace) are implementing the idea of "Pulsar
> release page automation" [1] and updating the workflow [2].
>
> I'll move the workflow to the pulsar/wiki/release folder [3] once it is
> finalized.
> And will move other documentation-related guides to the Contribution page
> [4] later.
>
> [1] https://github.com/apache/pulsar/discussions/17310
> [2] https://github.com/apache/pulsar-site/pull/242#issuecomment-1272700632
> [3] https://github.com/apache/pulsar/tree/master/wiki/release
> [4] https://pulsar.apache.org/contributing/
>
> Yu
>
> On Tue, Oct 4, 2022 at 10:21 PM Yunze Xu <yz...@streamnative.io.invalid>
> wrote:
>
> > TL; DR, we should add the Markdown documents about the pulsar-site repo
> > in GitHub. DON'T USE GOOGLEDOCS EVERYWHERE!
> >
> > ----
> >
> > Currently Pulsar's website is maintained in
> > https://github.com/apache/pulsar-site. However, I cannot find any
> > document of this document repo.
> >
> > As a contributor, if I want to contribute to this repo, I will look at
> > the README first:
> >
> > https://github.com/apache/pulsar-site/blob/main/README.md
> >
> > However, I can barely find what I concerns about in it:
> > - Where should I add the content
> > - What should I do before opening a PR (e.g. building a preview)
> > - How can I build a preview in my local env
> > - How will the web page be updated due to the changes of this repo
> >
> > If I were a frontend engineer, I might also want to know how to
> > develop the website for it.
> >
> > What I can find is:
> >
> > [Preview Website
> > Changes](
> > https://docs.google.com/document/d/1wszdtMRo6MhKbVaggPK7_bnKaC4TewuT--GWZZxJNGg/edit#heading=h.wu6ygjne8e35
> > )
> >
> > from
> > https://github.com/apache/pulsar-site/tree/main/site2/website-next.
> >
> > Yeah, I believe nobody will click into this directory if he cannot
> > find anything from the README.md in the root directory.
> >
> > BTW, the details are in the external GoogleDocs link in
> > https://github.com/apache/pulsar#documentation-1
> >
> > There is a terrible case recently:
> >
> > How to add the release note also changed after
> > https://github.com/apache/pulsar-site/pull/227, we need to update them
> > in JavaScript files. However, in
> >
> > https://github.com/apache/pulsar/blob/master/wiki/release/release-process.md#write-release-notes
> > ,
> > there is no update in [Pulsar Release Notes
> > Guide](
> > https://docs.google.com/document/d/1cwNkBefKyV6OPbEXnUrcCdVZi0i2BezqL6vAL7VqVC0/edit#
> > ).
> >
> > If the release manager wants to know how to contribute the release
> > notes, he might tend to find a previous PR like
> > https://github.com/apache/pulsar-site/pull/209. Unfortunately, it's
> > outdated. We have to update the `.js` files now, e.g.
> > https://github.com/apache/pulsar-site/pull/242
> >
> > IMO, we should add a guidance into the pulsar-site repo. In addition,
> > the documents should be maintained in GitHub as much as possible. It's
> > better not just pasting an external GoogleDocs link. We can use
> > GoogleDocs for the temporary changes, but we should present a stable
> > Markdown document in GitHub.
> >
> > Thanks,
> > Yunze
> >
> >
> >
> >
> >
Re: [Discussion] Questions about the pulsar-site management
Posted by Yu <li...@apache.org>.
Hi Yunze,
Thanks for your feedback!
We (@SignorMercurio, @urfreespace) are implementing the idea of "Pulsar
release page automation" [1] and updating the workflow [2].
I'll move the workflow to the pulsar/wiki/release folder [3] once it is
finalized.
And will move other documentation-related guides to the Contribution page
[4] later.
[1] https://github.com/apache/pulsar/discussions/17310
[2] https://github.com/apache/pulsar-site/pull/242#issuecomment-1272700632
[3] https://github.com/apache/pulsar/tree/master/wiki/release
[4] https://pulsar.apache.org/contributing/
Yu
On Tue, Oct 4, 2022 at 10:21 PM Yunze Xu <yz...@streamnative.io.invalid>
wrote:
> TL; DR, we should add the Markdown documents about the pulsar-site repo
> in GitHub. DON'T USE GOOGLEDOCS EVERYWHERE!
>
> ----
>
> Currently Pulsar's website is maintained in
> https://github.com/apache/pulsar-site. However, I cannot find any
> document of this document repo.
>
> As a contributor, if I want to contribute to this repo, I will look at
> the README first:
>
> https://github.com/apache/pulsar-site/blob/main/README.md
>
> However, I can barely find what I concerns about in it:
> - Where should I add the content
> - What should I do before opening a PR (e.g. building a preview)
> - How can I build a preview in my local env
> - How will the web page be updated due to the changes of this repo
>
> If I were a frontend engineer, I might also want to know how to
> develop the website for it.
>
> What I can find is:
>
> [Preview Website
> Changes](
> https://docs.google.com/document/d/1wszdtMRo6MhKbVaggPK7_bnKaC4TewuT--GWZZxJNGg/edit#heading=h.wu6ygjne8e35
> )
>
> from
> https://github.com/apache/pulsar-site/tree/main/site2/website-next.
>
> Yeah, I believe nobody will click into this directory if he cannot
> find anything from the README.md in the root directory.
>
> BTW, the details are in the external GoogleDocs link in
> https://github.com/apache/pulsar#documentation-1
>
> There is a terrible case recently:
>
> How to add the release note also changed after
> https://github.com/apache/pulsar-site/pull/227, we need to update them
> in JavaScript files. However, in
>
> https://github.com/apache/pulsar/blob/master/wiki/release/release-process.md#write-release-notes
> ,
> there is no update in [Pulsar Release Notes
> Guide](
> https://docs.google.com/document/d/1cwNkBefKyV6OPbEXnUrcCdVZi0i2BezqL6vAL7VqVC0/edit#
> ).
>
> If the release manager wants to know how to contribute the release
> notes, he might tend to find a previous PR like
> https://github.com/apache/pulsar-site/pull/209. Unfortunately, it's
> outdated. We have to update the `.js` files now, e.g.
> https://github.com/apache/pulsar-site/pull/242
>
> IMO, we should add a guidance into the pulsar-site repo. In addition,
> the documents should be maintained in GitHub as much as possible. It's
> better not just pasting an external GoogleDocs link. We can use
> GoogleDocs for the temporary changes, but we should present a stable
> Markdown document in GitHub.
>
> Thanks,
> Yunze
>
>
>
>
>