containers / containers/podman.io

[Refactor] Streamline README.md and move developer instructions to CONTRIBUTING.md

Open Beginner friendly
#585 2 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.