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

docs: update README and tidy up docs #619

Open
wants to merge 3 commits into
base: develop
Choose a base branch
from
Open

Conversation

Abhinandan-Purkait
Copy link
Member

@Abhinandan-Purkait Abhinandan-Purkait commented Jan 28, 2025

  • Streamline README to have relevant content.
  • Tidy up existing docs.
  • Move deprecated assets to deprecated folder.
  • Update changelog.
  • Update RELEASE process.
  • Remove changelog folder as that becomes a hassle to maintain.

CHANGELOG.md Outdated Show resolved Hide resolved
CHANGELOG.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
RELEASE.md Outdated Show resolved Hide resolved
3. If a release is an RC tag then PR should include the changes to remove the changelog from `changelog/v0.7.x` which are already mentioned in `zfs-localpv/CHANGELOG.md` as part of step number 1.
Once a release is created:-
1. The repo owner updates the release page changelog with all the necessary content.
2. The repo owner updates the [CHANGELOG.md](./CHANGELOG.md) file with the changelog for the release.
Copy link
Member

Choose a reason for hiding this comment

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

Ideally the CHANGELOG.md should be updated before the release and not after. One should be able to pull in the git repo and read the change summary on the CHANGELOG.md.

Updates after release requires online version control software like github to be present for viewing the changelog.

Copy link
Member Author

Choose a reason for hiding this comment

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

That's not entriely true, changelog is updated once the release it created. How does one add changelog before release?

Copy link
Member

Choose a reason for hiding this comment

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

The release notes on the github release listing can't be created, that's true. However, the CHANGELOG.md can be updated before the release.

Copy link
Member Author

Choose a reason for hiding this comment

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

Can you please give me the wording for the same.

Copy link
Member Author

Choose a reason for hiding this comment

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

changelogs/released/0.8.0-RC1/121-pawanpraka1 Outdated Show resolved Hide resolved
@@ -0,0 +1,347 @@
## Usage and Deployment

### Prerequisites
Copy link
Member

Choose a reason for hiding this comment

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

nit: Should contain minimum supported kubernetes version

Copy link
Member Author

Choose a reason for hiding this comment

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

Its there on the Readme

Copy link
Member Author

Choose a reason for hiding this comment

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

Do you want me to put it here as well?

Copy link
Member Author

Choose a reason for hiding this comment

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

Signed-off-by: Abhinandan Purkait <[email protected]>
RELEASE.md Outdated Show resolved Hide resolved
RELEASE.md Outdated

If any issues are found during the above stages, they are fixed and a new release candidate builds are generated.
If any issues are found during the above stages, they are fixed and the prerelease tag is overidden by the newer changes and are up for above action items again.
Copy link
Member

Choose a reason for hiding this comment

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

"and are up for above action items again" means?

Copy link
Contributor

Choose a reason for hiding this comment

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

What does this mean the tag is overridden?

btw s/overidden/overridden

Copy link
Member Author

Choose a reason for hiding this comment

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

What I mean is, the tag is a fixed one and newer changes also are included in the same tag, for example 2.7.1-prerelease will have all the incremental changes going into release/2.7 branch till 2.7.1 is released.

Copy link
Member Author

Choose a reason for hiding this comment

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

and are up for above action items again" means?

Means everytime a new change goes in release/x.y from the point in time from creation of the branch release/x.y, the same prerelease tag is to be used for all testing and those list of items prior to release.

Copy link
Contributor

Choose a reason for hiding this comment

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

What is this tag we're talking about here?

RELEASE.md Outdated Show resolved Hide resolved
RELEASE.md Outdated Show resolved Hide resolved
RELEASE.md Outdated Show resolved Hide resolved
RELEASE.md Outdated Show resolved Hide resolved
@@ -4,7 +4,7 @@ LocalPV-ZFS is a CSI driver for dynamically provisioning a volume in ZFS storage

### 2. How to install LocalPV-ZFS

Make sure that all the nodes have zfsutils-linux installed. We should go to the each node of the cluster and install zfs utils
Make sure that all the nodes have zfsutils-linux installed. We should go to the each node of the cluster and install zfs utils.
Copy link
Member

Choose a reason for hiding this comment

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

Do we need to specify any version of zfsutils-linux here?

Copy link
Contributor

Choose a reason for hiding this comment

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

Also need to ensure they're available on a specific path location right? Otherwise need to override it on the chart?

Copy link
Member Author

Choose a reason for hiding this comment

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

Do we need to specify any version of zfsutils-linux here?

That is specified in the README.

Copy link
Member Author

Choose a reason for hiding this comment

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

Also need to ensure they're available on a specific path location right? Otherwise need to override it on the chart?

No we check at all the possible places and use wherever we find them. So mostly should be fine.

Copy link
Contributor

Choose a reason for hiding this comment

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

we check at all the possible places

No we don't, this doesn't work on NixOS by default. And probably won't on other similar distros.
You have to either use custom location or create bind mounts for this to work.

docs/faq.md Outdated Show resolved Hide resolved
docs/quickstart.md Outdated Show resolved Hide resolved
docs/quickstart.md Outdated Show resolved Hide resolved
docs/quickstart.md Outdated Show resolved Hide resolved
docs/quickstart.md Outdated Show resolved Hide resolved
docs/quickstart.md Outdated Show resolved Hide resolved
docs/quickstart.md Outdated Show resolved Hide resolved
docs/quickstart.md Outdated Show resolved Hide resolved
docs/quickstart.md Outdated Show resolved Hide resolved
CHANGELOG.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Show resolved Hide resolved
README.md Show resolved Hide resolved
README.md Show resolved Hide resolved
docs/quickstart.md Outdated Show resolved Hide resolved
All nodes should have the same verion of zfsutils-linux installed. <BR>

```bash
$ apt-get install zfsutils-linux
Copy link
Contributor

Choose a reason for hiding this comment

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

Should make it clear this is for ubuntu?

Copy link
Member Author

Choose a reason for hiding this comment

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

Only for ubuntu as in? It will work for any linux distro right? Even though package name might be different?

Copy link
Contributor

Choose a reason for hiding this comment

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

We should clarify this example is just for ubuntu as command won't work for fedora or arch-linux for example

docs/quickstart.md Show resolved Hide resolved
docs/quickstart.md Outdated Show resolved Hide resolved
docs/quickstart.md Outdated Show resolved Hide resolved
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants