search

cncf / techdocs

CNCF TechDocs Team
https://www.cncf.io
Apache License 2.0
37 stars 26 forks source link

Docs: TUF docs Analysis and Improvement #261

Open Dindihub opened 1 week ago

Dindihub commented 1 week ago

This PR covers issue #162 CNCFSD-1516 Do a first look at the TUF project docs

This is an ongoing exercise so I will be adding content periodically. To see what I'm working on go to analyses/0012-TUF

Maintainers can review routinely and suggest changes.

nate-double-u commented 1 week ago

Thanks for this, @Dindihub; congrats on your selection to the mentorship program!

I'll let your mentors review this, but we do need each commit to be signed. You can see details on how to do that here: https://github.com/cncf/techdocs/pull/261/checks?check_run_id=26370655815. This, like the formatting workflows, doesn't have to happen right away, but we'll need the commits signed before the PR is approved (and it's easier to manage if you get to it earlier in the process).

/cc @chalin @JustinCappos @lukpueh

Dindihub commented 1 week ago

Thanks for this, @Dindihub; congrats on your selection to the mentorship program!

I'll let your mentors review this, but we do need each commit to be signed. You can see details on how to do that here: https://github.com/cncf/techdocs/pull/261/checks?check_run_id=26370655815. This, like the formatting workflows, doesn't have to happen right away, but we'll need the commits signed before the PR is approved (and it's easier to manage if you get to it earlier in the process).

/cc @chalin @JustinCappos @lukpueh

Noted. Thanks Nate

lukpueh commented 1 week ago

Thanks for the great recommendations, @Dindihub! Do you plan to work on any of those? :)

Also, what's the plan for this PR? You say, you want to add content periodically. So it should stay open? I can give it a thorough pass (for typos, etc.) when you think it's ready.

Dindihub commented 1 week ago

Thanks for the great recommendations, @Dindihub! Do you plan to work on any of those? :)

Also, what's the plan for this PR? You say, you want to add content periodically. So it should stay open? I can give it a thorough pass (for typos, etc.) when you think it's ready.

Thanks for asking @lukpueh . I thought to create this PR so you can see what I'm working on. I'll create an implementation soon once @chalin reviews my work.

I'll be sure to notify you and Justin to review once it's ready. I intend for this PR to stay open untill then , so you can review it as a whole. Thanks

chalin commented 4 days ago

Hi @Dindihub, thanks for the PR, and your patience in getting some feedback. Before we start a formal review, let's get all checks passing (fixing broken links etc), including the DCO requirements, as Nate pointed out. Let me know if you have any questions about how to do that.

Dindihub commented 4 days ago

Hi @Dindihub, thanks for the PR, and your patience in getting some feedback. Before we start a formal review, let's get all checks passing (fixing broken links etc), including the DCO requirements, as Nate pointed out. Let me know if you have any questions about how to do that.

Thanks for the review @chalin. Let me work on it again. I have some questions about DCO for you on Slack. Thanks

Dindihub commented 4 days ago

@Dindihub - let's change the naming convention for the pages in this project. Specifically, rename the TUF-abc.md files by dropping the TUF- prefix.

(Using a prefix made sense when the analysis was in a single file, but not here.)

The rename might also fix some of the broken links.

Noted. Thanks @chalin

chalin commented 3 days ago

@Dindihub - for each of the failed PR checks, click on Details at the extreme right to see the run log for any specific failed check.

For example, if you visit https://github.com/cncf/techdocs/actions/runs/9693237225/job/26773151326?pr=261, you'll see:

Run npm run check:format

> techdocs@0.0.0 check:format
> npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)

> techdocs@0.0.0 _check:format
> npx prettier --check .

npm warn exec The following package was not found and will be installed: prettier@3.3.2
Checking formatting...
[warn] analyses/00[12](https://github.com/cncf/techdocs/actions/runs/9693237225/job/26773151326?pr=261#step:4:13)-TUF/analysis.md
[warn] analyses/0012-TUF/implementation.md
[warn] Code style issues found in 2 files. Run Prettier with --write to fix.
[help] Run: npm run fix:format
Error: Process completed with exit code 1.

Notice the [help] line tells you which command to run on your local machine to fix the formatting issues.

Fix the formatting first (using npm run fix:format) and that will address many (if not all) of the markdown check failures.

Dindihub commented 3 days ago

@Dindihub - for each of the failed PR checks, click on Details at the extreme right to see the run log for any specific failed check.

For example, ... Notice the [help] line tells you which command to run on your local machine to fix the formatting issues.

Fix the formatting first (using npm run fix:format) and that will address many (if not all) of the markdown check failures.

Ah. Noted. Thanks