[Discussion] keep doc repo stay in pulsar repo?

[Yu <li...@apache.org>]

Hi Pulsarers,

As we move forward with PIP 87 [1], we’ve migrated the Pulsar website
contents to an independent repo, pulsar-site, per the agreement made by our
community [2].

This migration makes us think of the doc repo. After thinking twice, our
recommendation is to **keep the Pulsar doc repo as it is** in the pulsar
repo [3] rather than migrate it to the pulsar-site repo [4].

Context:

   - Currently, Pulsar doc and code are hosted in the same GitHub repo,
   which causes some doc management issues (such as hard to measure the
   quality and usage of doc).
   -

   Examples of other open source communities that use separate GitHub repos
   for doc and code are Kubesphere, PingCAP, Milvus. To some degree, it
   enhances the efficiency of doc management and development workflow.
   -

   Separate doc repo has many advantages, however, after weighing up pros
   and cons of the two methods, we do not choose it. We’ve summarized below
   both methods to highlight the benefits and limitations.


ACTION: Please review and vote within 72 hours. **If there is no discussion
or objection, we’ll keep it as it is (method 1).**

We’d love your feedback! Thanks!


~~~~~~~~~~~~~~~~~~


# Method 1

Pulsar doc and code are in the **same** GitHub repo.


## Advantages

1) Doc contributors do not need to change their habits.

Pulsar doc contributors are accustomed to updating docs at the pulsar repo
[3].

2) Manage code PRs and their relevant doc PRs and issues conveniently.

Contributors can get all the information about issues (eg. what’s the
issue, issue resolution process, etc) and link them in one repo.


## Disadvantages

1) To some degree, it’s difficult to improve the efficiency of doc
management and development workflow.

If doc and code are hosted in the same GitHub repo, it is hard to collect
and analyze doc metrics.


~~~~~~~~~~~~~~~~~~


# Method 2

Pulsar doc and code are in **different** GitHub repos.


## Advantages

1) Improve the efficiency of doc management and development workflow.

If doc is hosted in an independent GitHub repo, it is easier to measure the
quality and usage of our documentation.

For example, we can collect metrics from GitHub Insights or other tools
like SourceLevel [5], to understand dynamics and adjust appropriately.


### Disadvantages

1) Doc contributors need to change where they update documentation.

CHANGE: Pulsar doc contributors need to update docs at the pulsar-site repo
[4].
2) Doc commits are calculated in the pulsar-site rather than the pulsar
repo, which may decrease doc visibility.
3) Contributors need to manage code PRs and their relevant doc PRs and
issues in two different repos.

~~~~~~~~~~~~~~~~~~

[1] https://lists.apache.org/thread/vrd764pv66mbnctttk2h3dvvhls92bgy

[2] https://lists.apache.org/thread/06sl2mh5jm1llq12w5m4hw6pvfx32vkd

[3] https://github.com/apache/pulsar

[4] https://github.com/apache/pulsar-site

[5] https://sourcelevel.io/

Re: [Discussion] keep doc repo stay in pulsar repo?

[Michael Marshall <mm...@apache.org>]

Hi Yu,

I support keeping the docs repo in the main repo. I find it helpful to
be able to search through the docs along with the code, and as you
mention, it makes it easier for developers to contribute documentation
as a part of PRs that introduce new features.

My one concern is the `pulsar-site` branch--it has become quite large.
Given that we're keeping the branch in the main repo, do we plan to
delete some or all of its history to decrease the cost of `git fetch`
commands?

Thanks,
Michael


On Tue, Feb 15, 2022 at 9:25 PM Yu <li...@apache.org> wrote:
>
> Hi Pulsarers,
>
> Since there is no discussion and objection, we'll keep the doc repo stay in the pulsar repo and continue to move forward with PIP 87.

Re: [Discussion] keep doc repo stay in pulsar repo?

[Michael Marshall <mm...@apache.org>]

Hi Yu,

I support keeping the docs repo in the main repo. I find it helpful to
be able to search through the docs along with the code, and as you
mention, it makes it easier for developers to contribute documentation
as a part of PRs that introduce new features.

My one concern is the `pulsar-site` branch--it has become quite large.
Given that we're keeping the branch in the main repo, do we plan to
delete some or all of its history to decrease the cost of `git fetch`
commands?

Thanks,
Michael


On Tue, Feb 15, 2022 at 9:25 PM Yu <li...@apache.org> wrote:
>
> Hi Pulsarers,
>
> Since there is no discussion and objection, we'll keep the doc repo stay in the pulsar repo and continue to move forward with PIP 87.

Re: [Discussion] keep doc repo stay in pulsar repo?

[Yu <li...@apache.org>]

Hi Pulsarers,

Since there is no discussion and objection, we'll keep the doc repo stay in
the pulsar repo and continue to move forward with PIP 87.

Re: [Discussion] keep doc repo stay in pulsar repo?

[Yu <li...@apache.org>]

Hi Pulsarers,

Since there is no discussion and objection, we'll keep the doc repo stay in
the pulsar repo and continue to move forward with PIP 87.