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.

Sign up for GitHub

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

Jump to bottom

Migrate documentation to docs.sigstore.dev #822

Closed
lukehinds opened this issue Sep 29, 2021 · 26 comments · Fixed by sigstore/docs#54
Closed

Migrate documentation to docs.sigstore.dev #822

lukehinds opened this issue Sep 29, 2021 · 26 comments · Fixed by sigstore/docs#54
Assignees
@endorama @ChrisJBurns
Labels
good first issue Good for newcomers

Comments

@lukehinds
Copy link
Member

We now have a nice docs site, so let's start moving content into there.

Seeking volunteers to help with this and also add more content.
@lukehinds lukehinds added the good first issue Good for newcomers label Sep 29, 2021
@endorama
Copy link

endorama commented Oct 6, 2021

Happy to help with this! Which content should be migrated? Everything from the doc/ folder?

@lukehinds
Copy link
Member Author

Thanks @endorama , /doc is just auto generated stuff , most of its in the .md files in the root (including the main README.md)

@lukehinds lukehinds mentioned this issue Oct 12, 2021
Closed
@dlorenc
Copy link
Member

dlorenc commented Oct 12, 2021

+1, we should figure out a migration plan and cutoff to get everything into the other site.

@endorama
Copy link

I was going through the docs for the website, do I need an invite to Netlify CMS?

At the moment I would start migrating pages and writing a script to synchronize them between cosign and website repositories. This would allow to have the content on the website quickly with an easy path for manual updates.

What is the expected flow once the migration is finished? Will cosign docs still be in this repo or every contribution must/will happen in website repo?

@endorama endorama mentioned this issue Oct 13, 2021
Closed
@lukehinds
Copy link
Member Author

Already made a start on this (in fact it should be good to go)

sigstore/sigstore-website#67

@dlorenc
Copy link
Member

dlorenc commented Oct 16, 2021

Nice!

Now we have to figure out how to best link over to those docs from here, and what should stay here.

Maybe this readme can contain installation instructions, a quickstart, and then a link to the full docs on the website?

@dlorenc
Copy link
Member

dlorenc commented Oct 16, 2021

One other quick thing I noticed when browsing those docs: we should probably leave the specification files here in this repo:

https://docs.sigstore.dev/cosign/cosign_predicate_spec
https://docs.sigstore.dev/cosign/specifications

@endorama
Copy link

we should probably leave the specification files here in this repo

@dlorenc do you think is better to just link to the main branch version of those files from the docs website or duplicate the content?

@dlorenc
Copy link
Member

dlorenc commented Oct 27, 2021

@dlorenc do you think is better to just link to the main branch version of those files from the docs website or duplicate the content?

Yeah - linking to here would be best I think.

@endorama endorama mentioned this issue Oct 28, 2021
Merged
@ChrisJBurns
Copy link
Contributor

Just going through all the GFI's and found this one is the oldest, thought I'd offer my help to get it across the line :) - providing there's anything left to do @dlorenc @endorama @lukehinds ?

@haydentherapper
Copy link
Contributor

We should increase the number of examples in docs.sigstore.dev, we have lots of examples for container signing but not many for blob signing. https://github.com/sigstore/cosign/blob/main/KMS.md should be brought over to the docs.

Lots of documentation will need to be updated as part of #2534 also.

https://github.com/sigstore/cosign/tree/main/specs should be cleaned up and added.

@znewman01
Copy link
Contributor

Thanks so much @ChrisJBurns !

+1 to migrating lots of KMS.md along with README.md, EXAMPLES.md, KEYLESS.md, and IMPORT.md. We can leave a few simple README.md examples in, with a pointer back to docs.sigstore.dev.

Lots of documentation will need to be updated as part of #2534 also.

Agreed but I think because that's tracked separately it doesn't need to be addressed as part of this issue.

https://github.com/sigstore/cosign/tree/main/specs should be cleaned up and added.

IMO we should leave that in this repo. (We deliberately pulled it out in sigstore/sigstore-website#74)

@ChrisJBurns
Copy link
Contributor

ChrisJBurns commented Dec 20, 2022 •
edited
Loading

Thanks @znewman01 although not sure if I'm looking in the right place?

The file paths in the sigstore-website repo that is being used in @lukehinds PR above is content/en/cosign? But that path doesn't exist anymore?

Am I correct in assuming that we use content/docs/... ? If so, there doesn't really seem to be anything in there either. Additionally, I've clicked a couple of Edit this page links on the Docs site and they take me to the .md file on the docs branch in this (cosign) repo (but the file doesn't exist anymore).

There's also a couple of things that I'm getting mixed up by, mainly that (I believe) this PR is to port the docs from this repo into the sigstore-website one. However in the sigstore-website repo, there is a README.md sentence saying (2 months ago) that the cosign repo is where the docs live. 😄 .

So am a bit confused atm, are we porting over the docs from this repo into the sigstore-website repo, or are we just refactoring the docs that live in this repo, into the docs folder of this repo?

@ltagliaferri
Copy link

The documentation repo is now https://github.com/sigstore/docs (sigstore/sigstore-website is the frontend "Marketing" site for Sigstore)

The Cosign documentation is in content/en/cosign (https://github.com/sigstore/docs/tree/main/content/en/cosign)

I'm happy to collaborate on bringing more things over. There are a few known URL issues on the docs site, and I have a PR open to address those

@ChrisJBurns
Copy link
Contributor

Thank you @ltagliaferri I'm going to start with the README.md, EXAMPLES.md, KEYLESS.md, and IMPORT.md docs.

@znewman01
Copy link
Contributor

TYVM @ChrisJBurns !

I'll warn you right now: you may have to be a little patient because we may say "oh leave that in README.md" a bunch 😄

If you start with adding things to the docs before we copy them from Cosign (feel free to CC me in, I don't usually get docs repo notifications) that'll probably be safer.

@ChrisJBurns
Copy link
Contributor

ChrisJBurns commented Dec 29, 2022 •
edited
Loading

@znewman01 Shall do 👍 What I can do is put a NOTE: in the relevant parts of the README.md, EXAMPLES.md etc just to say a particular part has been migrated? Therefore, when folks are comfortable they can easily see what needs to be removed in future? Either that, or I can just raise an issue to remove the parts that have been successfully migrated? I'm easy either way :)

@ChrisJBurns ChrisJBurns mentioned this issue Dec 29, 2022
Merged
@znewman01
Copy link
Contributor

Just a note should be fine!

Will review your PR shortly, I'm unburying myself from a week's holiday right now :)

This was referenced Jan 2, 2023
Merged
Merged
@ChrisJBurns ChrisJBurns mentioned this issue Apr 10, 2023
Merged
@ChrisJBurns
Copy link
Contributor

sigstore/docs#123 will see to the last non README.md docs page that lives in the cosign repo root directory that we've spoke about on this issue.
Do we know what parts of the README.md we'd want to migrate over? Or is that a deeper discussion and something to possibly delay?

Also would we know what would be required to close this ticket? Are there a list of docs pages we want to migrate over, or have we done the majority of them? I ask because there are also the following:

Would we want to migrate those also?

@haydentherapper
Copy link
Contributor

I would prefer we don't migrate anything in the README over. At a glance, everything appears to be covered in documentation or is outdated.

Out of what's listed, USAGE is likely redundant, so I don't think it needs to be moved. The other three might fit somewhere, but it'd be good to confirm if they are redundant.

@ChrisJBurns
Copy link
Contributor

@haydentherapper Yep agreed on the USAGE.md point, I see a lot of duplicated information in there that we've already got on the docs sites, although worth confirming.

This was referenced Apr 12, 2023
Merged
Merged
Merged
Merged
Merged
Merged
@ChrisJBurns ChrisJBurns mentioned this issue May 11, 2023
Merged
@ChrisJBurns
Copy link
Contributor

ChrisJBurns commented May 11, 2023 •
edited
Loading

@lukehinds @znewman01 @haydentherapper @dlorenc @ltagliaferri @endorama

So I think we should be able to consider closing this ticket as of now.

The following docs have been migrated from cosign into the relevant docs pages and are all available on the https://docs.sigstore.dev/.

A deprecation note has been added to all of the above mentioned cosign doc pages and can be removed whenever you're ready. This should stop folks from adding more content to the pages and instead will redirect them to the official docs repository.

I haven't touched the cosign/README.md just because it seems we have to agree what bits to take out and what bits to leave in there. My recommendation as a first instance though is to probably remove the instances of "I" and replace with "We"?

Example:

"I believe this tool is complementary to TUF, and they can be used together. I haven't tried yet, but think we can also reuse a registry for TUF storage."

Would become:

"We believe this tool is complementary to TUF, and they can be used together. We haven't tried yet, but we think we can also reuse a registry for TUF storage."

There's only a couple of instances of this, so I'm nitpicking at this point 😄

I'm more than happy to do the README.md changes, as long as we can agree what changes we want to make with regards to the content it needs to have and content we can take out (as some of it is most likely covered on the docs site now).

@znewman
Copy link

znewman commented May 12, 2023

@ChrisJBurns Why am I tagged in this?

@znewman01
Copy link
Contributor

@znewman I think he meant me :)

@ChrisJBurns
Copy link
Contributor

@znewman Apologies, I meant @znewman01, I got a bit trigger happy with the send button 😢

@znewman01
Copy link
Contributor

Happy to close it out for now! Thanks for the hard work here @ChrisJBurns

This was referenced Aug 19, 2023
Open
Merged
lambdanis added a commit to lambdanis/tetragon that referenced this issue Mar 17, 2024
@lambdanis
docs: Fix cosign instructions
b59cfbb 
Cosign documentation was migrated to https://docs.sigstore.dev/ in
sigstore/cosign#822 and the markdown files were removed in sigstore/cosign#3587.
Tetragon documentation was linking to one of this files. Now it's linking to
https://docs.sigstore.dev/.

While here, remove `COSIGN_EXPERIMENTAL=1` from the cosign command for
verifying keyless-signed images. It's not required since cosign v2.0.0
(see https://blog.sigstore.dev/cosign-2-0-released/).

Signed-off-by: Anna Kapuscinska <anna@isovalent.com>
@lambdanis lambdanis mentioned this issue Mar 17, 2024
Merged
mtardy pushed a commit to cilium/tetragon that referenced this issue Mar 17, 2024
@lambdanis @mtardy
docs: Fix cosign instructions
899b46d 
Cosign documentation was migrated to https://docs.sigstore.dev/ in
sigstore/cosign#822 and the markdown files were removed in sigstore/cosign#3587.
Tetragon documentation was linking to one of this files. Now it's linking to
https://docs.sigstore.dev/.

While here, remove `COSIGN_EXPERIMENTAL=1` from the cosign command for
verifying keyless-signed images. It's not required since cosign v2.0.0
(see https://blog.sigstore.dev/cosign-2-0-released/).

Signed-off-by: Anna Kapuscinska <anna@isovalent.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@endorama endorama

@ChrisJBurns ChrisJBurns

Labels
good first issue Good for newcomers
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Adds Import Key Pair Docs ChrisJBurns/docs
8 participants
@znewman @endorama @znewman01 @dlorenc @ltagliaferri @lukehinds @haydentherapper @ChrisJBurns