Skip to content

docs: rewrite README and docs/ — records that the program cannot start #117

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

Open
willtheorangeguy wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs: rewrite README and docs/ — records that the program cannot start #117

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9511e79
docs: rewrite README and docs/ — records that the program cannot start
willtheorangeguy Aug 18, 2026
9fe14bb
docs: restore the original Windows entry in the credits table
willtheorangeguy Aug 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 41 additions & 107 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,153 +1,93 @@
<!-- Logo -->
<h1 align="center">
<img src="https://github.com/willtheorangeguy/ProgramVer/blob/master/docs/images/logo.png" height="250px" width="400px" alt="ProgramVer">
<img src="https://raw.githubusercontent.com/willtheorangeguy/.github/main/icons/ProgramVer/logo.png" height="250px" width="400px" alt="ProgramVer">
<br>
ProgramVer
<br>
</h1>

<!-- Copy -->
<h4 align="center">A Python version of Microsoft's 'winver', built to be customizable, and to show copyright info and licenses.</h4>
<h4 align="center">A Python version of Microsoft's <code>winver</code> — a copyright and licence window you drop into your own program.</h4>

<!-- Badges -->
<div align="center">
<!-- Stability -->
<img alt="PyPI Build State" src="https://github.com/willtheorangeguy/ProgramVer/actions/workflows/push-to-pypi.yml/badge.svg">
<!-- Stability -->
<img alt="Pylint State" src="https://github.com/willtheorangeguy/ProgramVer/actions/workflows/pylint.yml/badge.svg">
<!-- Tests -->
<img alt="Tests State" src="https://github.com/willtheorangeguy/ProgramVer/actions/workflows/tests.yml/badge.svg">
<!-- CodeQL -->
<img alt="CodeQL State" src="https://github.com/willtheorangeguy/ProgramVer/actions/workflows/codeql-analysis.yml/badge.svg">
<!-- Version -->
<img alt="GitHub Version" src="https://img.shields.io/github/v/release/willtheorangeguy/ProgramVer?include_prereleases">
<!-- Issues -->
<img alt="GitHub Issues" src="https://img.shields.io/github/issues/willtheorangeguy/ProgramVer">
<!-- Pull Requests -->
<img alt="GitHub Pull Requests" src="https://img.shields.io/github/issues-pr/willtheorangeguy/ProgramVer">
<!-- Discord -->
<img alt="Discord Server ID" src="https://img.shields.io/discord/1016437709247619092">
<!-- Downloads -->
<img alt="Downloads" src="https://img.shields.io/github/downloads/willtheorangeguy/ProgramVer/total">
<!-- Language Count -->
<img alt="GitHub Languages" src="https://img.shields.io/github/languages/count/willtheorangeguy/ProgramVer">
</div>

<!-- Navigation -->
<p align="center">
<a href="#status">Status</a> •
<a href="#key-features">Key Features</a> •
<a href="#download">Download</a> •
<a href="#how-to-use">How To Use</a> •
<a href="#installation">Installation</a> •
<a href="#usage">Usage</a> •
<a href="#documentation">Documentation</a> •
<a href="#support">Support</a> •
<a href="#contributing">Contributing</a> •
<a href="#changelog">Changelog</a> •
<a href="#credits">Credits & Contributors</a>
<a href="#credits">Credits</a> •
<a href="#license">License</a>
</p>

<!-- Screenshot(s) -->
<!-- Screenshot -->
<div align="center">
<img alt="Main image" src="https://github.com/willtheorangeguy/ProgramVer/blob/master/docs/images/welcome.png">
<img alt="ProgramVer window" src="https://raw.githubusercontent.com/willtheorangeguy/.github/main/icons/ProgramVer/welcome.png">
</div>

## Key Features

* Display a version window.
* Can be called and imported as a function.
* Links to License text.
* Links to EULA text.
* Includes logo and Python Powered images.
* Cross platform.
## Status

## Download
**Currently broken as shipped.** `ProgramVer()` loads `imgs/dfdlogo.gif`, which is not in the repository, so the window fails before it appears. The two buttons read `LICENSE.txt` and `EULA.txt`, neither of which exists either.

You can **[download](https://github.com/willtheorangeguy/ProgramVer/releases/latest) the source code** to run the scripts from the command line on Windows, macOS and Linux. **This will require [Python](https://www.python.org/downloads/).**
The test suite passes — it mocks every file access and every widget — so CI is green and the program still cannot start. Details and suggested fixes are in [`docs/internal/known-issues.md`](docs/internal/known-issues.md).

You can **[download](https://github.com/willtheorangeguy/ProgramVer/releases/latest) the latest executable version** of ProgramVer for Windows. **This does not require Python.**
The template is sound and the customisation points are real; it needs its assets back.

## How To Use

To run the application, you can use [Git and the Python Interpreter](https://github.com/willtheorangeguy/ProgramVer/main/README.md#git), which allows you to clone and run the application, or [`pip`](https://github.com/willtheorangeguy/ProgramVer/main/README.md#pip) to create a command line application.
## Key Features

### Git
- A `winver`-style window: logo, program name and version, trademark notice, licence blurb.
- **Open License** and **Open EULA** buttons that display the full text in their own windows.
- Importable as a function, so you can wire it to your own program's About menu.
- Python-Powered badge included.
- Pure standard library — Tkinter only.
- Cross-platform.

To clone and run this application, you'll need [Git](https://git-scm.com/downloads) and [Python](https://www.python.org/downloads/) installed on your computer. If you would rather not use Git, you can just download the script from GitHub above. From your command line:
## Installation

```bash
# Clone this repository
$ git clone https://github.com/willtheorangeguy/ProgramVer

# Go into the repository
$ cd ProgramVer

# Run the CLI
$ python main.py
git clone https://github.com/willtheorangeguy/ProgramVer
cd ProgramVer
python main.py
```

### `pip`
See [`docs/installation.md`](docs/installation.md), including what you need to supply before it runs.

You can install the program from the [Python Package Index](https://pypi.org/project/programver/) through `pip`.

```bash
# Install via pip
$ pip install programver
## Usage

# Run the CLI
$ programver
```python
from main import ProgramVer
ProgramVer()
```

However, you may want to add the version window to your program. To do so, follow these steps:
Every string in the window is meant to be edited for your project — see [`docs/configuration.md`](docs/configuration.md).

1. Download the latest source code release from [GitHub Releases](https://github.com/willtheorangeguy/ProgramVer/releases/latest) page.
2. Extract the source code files using a program like [7-Zip](https://www.7-zip.org/).
3. Copy the `ProgramVer.py` file to your project's main directory.
4. Import ProgramVer by adding `from ProgramVer import *` to your Python `import` statements.
5. Call ProgramVer through the `ProgramVer()` function.
6. Enjoy your new version window!
## Documentation

## Support

Customization for ProgramVer can be found in the [`CUSTOMIZATION`](https://github.com/willtheorangeguy/ProgramVer/blob/master/docs/CUSTOMIZATION.md) doc. More documentation is available in the **[Documentation](https://github.com/willtheorangeguy/ProgramVer/tree/master/docs)** and on the **[Wiki](https://github.com/willtheorangeguy/ProgramVer/wiki)**. If more support is required, please open a **[GitHub Discussion](https://github.com/willtheorangeguy/ProgramVer/discussions)** or join our **[Discord](https://discord.gg/x3G8adwVUe)**.

## Testing

ProgramVer includes a comprehensive test suite to ensure code quality and reliability. The test suite achieves 100% code coverage for the main module.
Full documentation lives in [`docs/`](docs/README.md):
[Quickstart](docs/quickstart.md) · [Installation](docs/installation.md) · [Configuration](docs/configuration.md) · [Architecture](docs/architecture.md) · [Development](docs/development.md) · [Testing](docs/testing.md) · [FAQ](docs/faq.md) · [Troubleshooting](docs/troubleshooting.md) · [Roadmap](docs/roadmap.md)

### Running Tests

To run the test suite locally:

```bash
# Install test dependencies
pip install -r requirements.txt

# Run tests (Linux)
xvfb-run -a python -m pytest tests/ -v

# Run tests (Windows/macOS)
python -m pytest tests/ -v

# Run tests with coverage
python -m pytest tests/ --cov=main --cov-report=term-missing
```

For more information about testing, see the [tests README](tests/README.md).

### Continuous Integration

Tests are automatically run on GitHub Actions for every push and pull request across:
## Support

- Operating Systems: Ubuntu, Windows, and macOS
- Python Versions: 3.9, 3.10, 3.11, and 3.12
Open a [GitHub Discussion](https://github.com/willtheorangeguy/ProgramVer/discussions), file an [issue](https://github.com/willtheorangeguy/ProgramVer/issues/new/choose), or join the [Discord](https://discord.gg/x3G8adwVUe).

## Contributing

Please contribute using [GitHub Flow](https://guides.github.com/introduction/flow). Create a branch, add commits, and [open a pull request](https://github.com/willtheorangeguy/ProgramVer/compare).

Please read [`CONTRIBUTING`](https://github.com/willtheorangeguy/.github/blob/main/CONTRIBUTING.md) for details on our [`CODE OF CONDUCT`](https://github.com/willtheorangeguy/.github/blob/main/CODE_OF_CONDUCT.md), and the process for submitting pull requests to us.

## Changelog

See the [`CHANGELOG`](CHANGELOG.md) file for details.
See the org-wide [Contributing Guide](https://github.com/willtheorangeguy/.github/blob/main/CONTRIBUTING.md) and [Code of Conduct](https://github.com/willtheorangeguy/.github/blob/main/CODE_OF_CONDUCT.md).

## Credits

Expand All @@ -172,16 +112,10 @@ This software uses the following open source packages, projects, services or web
</tr>
</table>

## Contributors

* [@willtheorangeguy](https://github.com/willtheorangeguy) - Sponsor on [PayPal](https://paypal.me/wvdg44?country.x=CA&locale.x=en_US)

## You may also like...

* [PyWorkout](https://github.com/willtheorangeguy/PyWorkout) - A minimal CLI to keep you inspired during your workout!
* [PyAvatar](https://github.com/willtheorangeguy/PyAvatar) - Easily display all of your creative avatars to keep them consistent across websites.
* [Periodic Table Info](https://github.com/willtheorangeguy/Periodic-Table-Info) - Print all the elements in the Periodic Table of the Elements, with an interactive prompt to learn more.
Sponsor [@willtheorangeguy](https://github.com/willtheorangeguy) on [PayPal](https://paypal.me/wvdg44?country.x=CA&locale.x=en_US).

## License

This project is licensed under the [MIT License](https://mit-license.org/) - see the [`LICENSE`](LICENSE.md) file for details.
MIT — see [`LICENSE.md`](LICENSE.md).

> Note the window itself currently displays a GPL blurb and a different copyright holder. That text is placeholder content meant to be replaced per project, but it does not match this repository's own licence — see [`docs/internal/known-issues.md`](docs/internal/known-issues.md).
56 changes: 0 additions & 56 deletions docs/CUSTOMIZATION.md
View file
Open in desktop

This file was deleted.

63 changes: 54 additions & 9 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,57 @@
# ProgramVer Documentation
# ProgramVer — Documentation

This folder includes all of the docs for ProgramVer. More can be found on the [wiki](https://github.com/willtheorangeguy/ProgramVer/wiki).
A `winver`-style copyright and version window for your own Python programs: a logo, a version
line, a trademark notice, a licence blurb, and buttons that open the full licence and EULA.

```text
├── docs
| ├── images
| ├── CUSTOMIZATION.md
| ├── TESTING.md
| ├── USAGE.md
└── README.md
```
ProgramVer/
├── main.py get_resource_path, openLicense, openEULA, ProgramVer
├── imgs/ the window's images
├── tests/test_main.py
└── docs/ this documentation
```

## Pages

- [Quickstart](./quickstart.md) — run it, and what you must supply first
- [Installation](./installation.md) — source, PyPI, executable
- [Configuration](./configuration.md) — every string and image to change for your project
- [Architecture](./architecture.md) — three functions, one window
- [Development](./development.md) — packaging and style
- [Testing](./testing.md) — the suite, and what it does not check
- [FAQ](./faq.md) — why it fails, what to customise, why GPL text
- [Troubleshooting](./troubleshooting.md) — missing files, blank windows
- [Roadmap](./roadmap.md) — direction and non-goals
- [Known issues](./internal/known-issues.md) — recorded defects

## It does not run as shipped

Three files the code needs are absent from the repository:

| Wanted by | File | Present |
|---|---|---|
| `ProgramVer()` | `imgs/dfdlogo.gif` | **No** |
| `openLicense()` | `LICENSE.txt` | **No** — the repo has `LICENSE.md` |
| `openEULA()` | `EULA.txt` | **No** |

The first stops the window opening at all. `MANIFEST.in` lists `imgs/dfdlogo.gif` for packaging,
so it is expected to exist and does not.

CI is green throughout, because the test suite mocks file access and every Tk widget. See
[`internal/known-issues.md`](./internal/known-issues.md).

## What it is for

Microsoft's `winver` shows a small window with the product name, version, and licensing notice.
ProgramVer is the same idea for a Python program: a function you call from an About menu that
presents the same information, with the licence text one click away.

The design assumption is that **you edit it**. Program name, version, trademark line, licence
blurb, and the two document filenames are all literals in `main.py`, each with a
`# change as needed` comment. That is the intended workflow — see
[Configuration](./configuration.md).

## Standard library only

Tkinter and nothing else. Dropping `main.py` into a project adds no dependencies, which is the
point of a component meant to be copied rather than depended on.
Loading
Loading