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

User guide contributor guide #701

Open
aburdenthehand opened this issue Jul 21, 2023 · 18 comments · May be fixed by #795
Open

User guide contributor guide #701

aburdenthehand opened this issue Jul 21, 2023 · 18 comments · May be fixed by #795
Assignees
Labels
good-first-issue Identifies an issue that has been specifically created or selected for first-time contributors. lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed.

Comments

@aburdenthehand
Copy link
Contributor

It would be good to update our contributor guide for KubeVirt docs to capture some of the conventions. The current guidelines are very high level, and the repo readme focuses on test builds - all good stuff, but some lower level guidance for things like basic structure, style, and conventions like version support and when to deprecate content etc would be useful.

Links:
https://kubevirt.io/user-guide/contributing/ (currently an issue already open about the multiple redirects to get to this page: #659 )
https://github.com/kubevirt/user-guide

@aburdenthehand aburdenthehand added the good-first-issue Identifies an issue that has been specifically created or selected for first-time contributors. label Jul 21, 2023
@pragatisaikia
Copy link

May I know exactly what changes are we suppose to make to which files.

@aburdenthehand
Copy link
Contributor Author

aburdenthehand commented Aug 25, 2023

Hi @pragatisaikia - thank you for your enthusiasm and patience!
I think we will want to create a new file, and I think the best place for it will be in the root directory of the user-guide repo.
We can call it 'docs-guidelines.md'

To start with, we can copy a couple of the relevant points from the blog guidelines, namely:

- Follow [Kramdown Quick Reference](https://kramdown.gettalong.org/quickref.html) for syntax reference
- Split the contents in sections using the different levels of headers that Markdown offers
  - Keep in mind that once rendered, the title you set in the Front Matter data will use `H1`, so start your sections from `H2`
- [Code blocks](https://kramdown.gettalong.org/syntax.html#code-blocks), use them for:
  - code snippets
  - file contents
  - console commands
  - ...
  - Use the proper tag to let the renderer what type of contents your including in the block for syntax highlighting
 - Don't include a command prompt in console commands, to simplify copy/paste.

We can postpone the version support for the moment as it is still being discussed.
Thanks!

@UncleWeeds
Copy link

I would like to work on this

@aburdenthehand
Copy link
Contributor Author

@pragatisaikia - are you still interested in working on this? If not, I will assign @UncleWeeds

@pragatisaikia
Copy link

@pragatisaikia - are you still interested in working on this? If not, I will assign @UncleWeeds

I'm looking into it. If not resolved, I'll mention asap.

@UncleWeeds
Copy link

@aburdenthehand it's been a while can I start working on this

@pragatisaikia
Copy link

@aburdenthehand it's been a while can I start working on this

I think you can work on this

@UncleWeeds
Copy link

/assign

@kubevirt-bot
Copy link
Contributor

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

/lifecycle stale

@kubevirt-bot kubevirt-bot added the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label Jan 18, 2024
@kubevirt-bot
Copy link
Contributor

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

/lifecycle rotten

@kubevirt-bot kubevirt-bot added lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed. and removed lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. labels Feb 17, 2024
@kubevirt-bot
Copy link
Contributor

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

/close

@kubevirt-bot
Copy link
Contributor

@kubevirt-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

@aburdenthehand aburdenthehand removed the lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed. label Apr 4, 2024
@chuot803
Copy link

Hi! My group and I from UT Austin are interested on working on this :) I was wondering what work has already been done towards this issue and what else we would need to add. Thanks!

@aburdenthehand
Copy link
Contributor Author

Hello @chuot803 - I'm not aware of any movement on this. From my point of view you are very welcome to work on this.
@UncleWeeds ?

@tbunch1
Copy link

tbunch1 commented May 2, 2024

Hi, I'm working with Lindsey. You mentioned adding information about when to deprecate content. When should that be? Or where can I find information on things like that?

@aburdenthehand
Copy link
Contributor Author

@tbunch1 - Great question. We can use our support matrix to guide us here.
Once it passes 3 K8s versions out of date (ie, if it's no longer present on our matrix at all) then we can safely remove it. This gives folks ~1 year out of support.

@tbunch1 tbunch1 linked a pull request May 4, 2024 that will close this issue
8 tasks
@kubevirt-bot
Copy link
Contributor

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

/lifecycle stale

@kubevirt-bot kubevirt-bot added the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label Aug 1, 2024
@kubevirt-bot
Copy link
Contributor

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

/lifecycle rotten

@kubevirt-bot kubevirt-bot added lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed. and removed lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. labels Aug 31, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
good-first-issue Identifies an issue that has been specifically created or selected for first-time contributors. lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

6 participants