search

kubernetes / contributor-site

Code for kubernetes.dev
https://www.kubernetes.dev
Apache License 2.0
63 stars 147 forks source link

Building Kubernetes page is not beginner friendly #467

Closed adityasamant25 closed 3 weeks ago

adityasamant25 commented 5 months ago

The Building Kubernetes page is not beginner friendly.

I have been trying to make a containerised build work on my Local Mac laptop for 2 days without success.

The following items need better explaining in my opinion

  1. Pre-requisites: For the Docker Desktop, it is not sufficient to mention a requirement of 8 GB memory for the Docker VM.. There should be a mention for minimum CPU and Storage allocation to the Docker VM. Example: My Docker VM had 60 GB of storage allocated to it and the unit test executions failed with No space left on deviceerrors. I increased it to 120 GB and I was able to overcome the space issue, but I have no idea if 120 GB is recommended or not. This should be specified in the document.

  2. Key scripts: This section describes the scripts available and what each script does. However, for a reader who is a beginner, it does not mention the order in which the scripts should be executed or tried. Example: If my goal is to run all the unit tests on my local machine, it is enough to directly run build/run.sh make test? Is there any pre-requisite to maybe run build/run.sh make first?

There should be a clear step-by-step instruction describing the order in which these scripts should be run for a beginner who has no prior experience in this. The reader should not have to guess this.

  1. There is no troubleshooting section: Some frequently occurring errors may be documented as a troubleshooting section. When the unit tests fail, a beginner has no idea where to look for the execution logs or how to troubleshoot the issue.

These points are hampering the experience for a developer who is trying to get his/her local build up and running.

BenTheElder commented 5 months ago

The points for 1) are a moving target as the project evolves and many active contributors are building on linux instead, PRs welcome!

If my goal is to run all the unit tests on my local machine, it is enough to directly run build/run.sh make test? Is there any pre-requisite to maybe run build/run.sh make first?

No, makefiles can encode ordering requirements (one of the main uses!) it would be unusual to require a manual ordering of make targets.

When the unit tests fail, a beginner has no idea where to look for the execution logs or how to troubleshoot the issue.

Debugging unit tests isn't exactly in scope for this particular document.

k8s-triage-robot commented 2 months ago

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

k8s-triage-robot commented 1 month ago

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

k8s-triage-robot commented 3 weeks ago

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

k8s-ci-robot commented 3 weeks ago

@k8s-triage-robot: Closing this issue, marking it as "Not Planned".

In response to [this](https://github.com/kubernetes/contributor-site/issues/467#issuecomment-2168636252): >The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs. > >This bot triages issues according to the following rules: >- After 90d of inactivity, `lifecycle/stale` is applied >- After 30d of inactivity since `lifecycle/stale` was applied, `lifecycle/rotten` is applied >- After 30d of inactivity since `lifecycle/rotten` was applied, the issue is closed > >You can: >- Reopen this issue with `/reopen` >- Mark this issue as fresh with `/remove-lifecycle rotten` >- Offer to help out with [Issue Triage][1] > >Please send feedback to sig-contributor-experience at [kubernetes/community](https://github.com/kubernetes/community). > >/close not-planned > >[1]: https://www.kubernetes.dev/docs/guide/issue-triage/ Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes-sigs/prow](https://github.com/kubernetes-sigs/prow/issues/new?title=Prow%20issue:) repository.