+1 I support moving them to the website repo.
Thanks, Penghui On Mon, Dec 19, 2022 at 12:04 PM Yunze Xu <y...@streamnative.io.invalid> wrote: > +1. The most significant point to me is that we can preview all the > content of the website without synchronizing contents from the > apache/pulsar repo. > > Thanks, > Yunze > > On Mon, Dec 19, 2022 at 9:53 AM Li Li <urf...@apache.org> wrote: > > > > +1, That’s a good idea. > > > > > On Dec 16, 2022, at 07:07, tison <wander4...@gmail.com> wrote: > > > > > > Hi, > > > > > > After several works around the build flow of our official > website[1][2][3], > > > the content sync and site build flow is debuggable and reproducible > now. > > > > > > However, compared to other Apache projects' websites' project layouts > and > > > workflow, we still meet two challenges on the Pulsar site: > > > > > > 1. We don't have a pre-commit workflow for any website-related changes. > > > Thus, we don't detect broken links or syntax errors when reviewing new > > > patches[4][5][6]. > > > 2. The website's content is two-level down in `site2/website-next` for > > > historical reasons, which is confusing for contributors. > > > > > > To overcome these two shortcomings, I propose the following: > > > > > > 1. Move the website's content to the root level, then we have a > first-class > > > Docu&yarn-based JS project layout. It's more convenient and familiar to > > > related developers. > > > 2. Host the source of docs in the site repo (apache/pulsar-site) > instead of > > > under `site2` folder in the main repo and do content sync. > > > > > > Below are the pros and cons: > > > > > > Pros > > > > > > 1. Obviously, we have the pre-commit workflow now. And since we host > the > > > source of docs in one repo, we don't have to run the pre-commit > workflow in > > > two places, which can be quite cumbersome to implement. > > > 2. The size of the source release of the main repo can be reduced a > lot. > > > Currently, 63MB out of 140MB of the sources are taken by the site2 > folder, > > > which we can remove totally. In addition, we carry out full-versioned > docs > > > every release. > > > 3. We can clean up a large portion of "integration" to debug the site > > > brittlely on the main repo[7] (etc.) and redundant contribution > guide[8]. > > > This way, when updating docs, we can preview the result in one repo > instead > > > of actually doing the sync on the fly. In addition, this integration > blocks > > > we move the website content to the top level since it makes strong > > > assumptions about the relative layout. > > > > > > Cons > > > > > > The most significant con is that we cannot update the code and docs in > one > > > patch against apache/pulsar now. You must open a new pull request to > > > apache/pulsar-site, cross-reference each other and manage the merge > order > > > (synchronization). > > > > > > Alternatives: > > > > > > To resolve the versioned docs issue, an alternative is to host only the > > > user docs along with each version, like Flink does[9]. But it both > detaches > > > from the Docu framework and requires significant development efforts. > > > > > > Since it can explicitly change the development flow (that is, you > should > > > now update docs separately), I am starting this discussion here to > reach > > > for your feedback. > > > > > > Welcome to leave your comments! > > > > > > Best, > > > tison. > > > > > > [1] https://pulsar.apache.org/ > > > [2] https://github.com/apache/pulsar-site > > > [3] https://github.com/apache/pulsar/issues/18014 > > > [4] https://github.com/apache/pulsar/issues/17599 > > > [5] https://github.com/apache/pulsar/pull/17863#discussion_r990174850 > > > [6] https://github.com/apache/pulsar/pull/17853#discussion_r991803704 > > > [7] > > > > https://github.com/apache/pulsar/blob/b1f9e351fa4d5aba197d33cfc0c536516b55b61f/site2/website/start.sh > > > [8] > > > > https://pulsar.apache.org/contribute/document-preview/#preview-documentation-changes > > > [9] https://github.com/apache/flink/tree/master/docs > > >
