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 <y...@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 > > > > >
