Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix(docs): update links in isolation docs #13295

Closed
wants to merge 2 commits into from
Closed

fix(docs): update links in isolation docs #13295

wants to merge 2 commits into from

Conversation

ericsyh
Copy link
Contributor

@ericsyh ericsyh commented Dec 14, 2021

Signed-off-by: Eric Shen ericshenyuhao@outlook.com

Motivation

The command links in https://pulsar.apache.org/docs/en/administration-isolation/ are using https://pulsar.apache.org/tools/pulsar-admin/ which is not clear for users to get to the target command.

Modifications

Update the links in https://pulsar.apache.org/docs/en/administration-isolation/ to target command docs.

Verifying this change

  • Make sure that the change passes the CI checks.

(Please pick either of the following options)

This change is a trivial rework / code cleanup without any test coverage.

(or)

This change is already covered by existing tests, such as (please describe tests).

(or)

This change added tests and can be verified as follows:

(example:)

  • Added integration tests for end-to-end deployment with large payloads (10MB)
  • Extended integration test for recovery after broker failure

Does this pull request potentially affect one of the following parts:

If yes was chosen, please highlight the changes

  • Dependencies (does it add or upgrade a dependency): (no)
  • The public API: (no)
  • The schema: (no)
  • The default values of configurations: (no)
  • The wire protocol: (no)
  • The rest endpoints: (no)
  • The admin cli options: (no)
  • Anything that affects deployment: (no)

Documentation

Check the box below and label this PR (if you have committer privilege).

Need to update docs?

  • doc-required

    (If you need help on updating docs, create a doc issue)

  • no-need-doc

    (Please explain why)

  • doc

    (If this PR contains doc changes)

Signed-off-by: Eric Shen <ericshenyuhao@outlook.com>
@github-actions github-actions bot added the doc Your PR contains doc changes, no matter whether the changes are in markdown or code files. label Dec 14, 2021
Copy link
Contributor

@Huanli-Meng Huanli-Meng left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

leave one comment. PTAL

@@ -31,7 +31,7 @@ pulsar-admin ns-isolation-policy set options

```

For more information about the command `pulsar-admin ns-isolation-policy set options`, see [here](https://pulsar.apache.org/tools/pulsar-admin/).
For more information about the command `pulsar-admin ns-isolation-policy set`, see [here](https://pulsar.apache.org/tools/pulsar-admin/2.8.0-SNAPSHOT/#-em-set-em-).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why add a 2.8.0 link in 2.7.2 release?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a mistake, i'll update it.

Signed-off-by: Eric Shen <ericshenyuhao@outlook.com>
Copy link
Contributor

@Huanli-Meng Huanli-Meng left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@@ -22,7 +22,7 @@ You can set a namespace isolation policy for a cluster using one of the followin
pulsar-admin ns-isolation-policy set options
```

For more information about the command `pulsar-admin ns-isolation-policy set options`, see [here](https://pulsar.apache.org/tools/pulsar-admin/).
For more information about the command `pulsar-admin ns-isolation-policy set`, see [here](https://pulsar.apache.org/tools/pulsar-admin/2.8.0-SNAPSHOT/#-em-set-em-).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ericsyh thanks for your consideration.
However, please do not change these general links to specified links, or else we need to update them for each release, there might be hundreds of occurrences. So here, we use general links on purpose.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. But it is confusing to me that why we need to have docs for each patch version? In my understanding, patch version onlly including bug fix and performance improvements and new features are only included in major and minor verion. So, we just need to keep one version docs for each minor version which means all 2.8.x verions just use a unified docs 2.8.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor versions include code improvements which need to update docs as well
For example,

  • Websocket should pass the encryption context to the consumers #12539 need to update docs for 2.8.2 and 2.9.1, which means no need to update doc versions before 2.8.1
  • Another example is, let's say, after a minor version is released, three months later, there is a patch to that release and needs to update docs, we need to make specific doc changes to that release as well

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

emmmm, #12539 seems a function enhenment PR and actually i think it should be released in a new minor version like 2.10.0 rathar than patch version 2.8.2 and 2.9.1.

I take a look at other open source projects, most of them just maintain the minor version docs:

截屏2021-12-16 下午12 43 15

It's really a heavy burden to maintain the docs for each patch version.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. The code changes Websocket should pass the encryption context to the consumers #12539 go into major and minor versions, so doc changes go those versions as well
    image

  2. Yes, Pulsar maintains versioned docs as well. For each minor version, for example, 2.7.x, you never know whether there might be code (doc) changes after it is released, so we maintain all of them for completeness
    image

@ericsyh ericsyh closed this Dec 17, 2021
@ericsyh ericsyh deleted the fix-isolation-docs branch December 19, 2021 12:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Your PR contains doc changes, no matter whether the changes are in markdown or code files.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants