containers / containers/podman.io
[Refactor] Streamline README.md and move developer instructions to CONTRIBUTING.md
- Dominant language
- TypeScript
- Stars
- 108
- Forks
- 188
- Avg merge
- 9d 15h
- Merged PRs (30d)
- 11
Description
## Summary
This issue proposes splitting the current `README.md` into two focused files: a streamlined `README.md` for visitors, and a new `CONTRIBUTING.md` for developer/build instructions.
---
## Why This Matters
For most visitors, the `README.md` is the very first thing they see when they land on a repository. Its job is to quickly answer a few basic questions: what is this project, why does it exist, and where can I see it live. When that file is dominated by dense, low-level build and deployment instructions, it becomes harder for newcomers to quickly understand the project, and it can make an otherwise well-maintained repository feel cluttered or less approachable.
Separating "what is this project" from "how do I develop on it" is a widely followed convention in open-source projects, and I think it would make `containers/podman.io` easier to navigate for both casual visitors and prospective contributors.
## Problem
Currently, the `README.md` for the `podman.io` repository contains a large amount of valuable but low-level developer content mixed in with introductory project information, including:
- Build Locally
- Testing on your Virtual Machine
- Deployment
- How to Update the Podman.io Website
- Configuration Information
While all of this information is useful, its presence makes the top-level README dense and harder to scan for someone simply trying to understand the project.
## Proposed Solution
Split the current `README.md` into two separate, focused files:
### 1. `README.md` (Streamlined)
- Keep only high-level information about the Podman website project
- Include badges (build status, license, etc.)
- Provide links to the live `podman.io` site and the main Podman codebase
- Add a brief pointer to `CONTRIBUTING.md` for anyone who wants to build or contribute to the site
### 2. `CONTRIBUTING.md` (New File)
- Move all existing technical instructions here, including:
- Build Locally
- Testing on your Virtual Machine
- Deployment
- How to Update the Podman.io Website
- Configuration Information
---
## Additional Context
If the maintainers are supportive of this direction, I'd be happy to open a PR to create `CONTRIBUTING.md` and clean up `README.md` accordingly.
Contributor guide
No contributing guide indexed for this repository
Research direction
Review the existing README.md and identify the listed developer sections: Build Locally, Testing on your Virtual Machine, Deployment, How to Update the Podman.io Website, and Configuration Information. Move those instructions into a new CONTRIBUTING.md, leaving README.md focused on the project, badges, links, and a pointer to the contribution guide. Done means both files are focused and the moved instructions remain intact.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100