Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Refactor repository structure for easier maintenance

Open
#414 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Refactor
Clarity
Mostly clear
Activity status
Stale
Domain
tooling

Research direction

Start by reading the existing index.yml and the per-application manifests under the category directories, then inspect the Bottles client’s current manifest-scanning behavior. Compare the proposed meta.yml, filename-derived names and categories, Icon, Event, and Hidden fields with the current format. Done means the repository structure and client behavior are migrated without outdated clients failing.

Written by the indexing model from the issue text.

Description

As discussed in #413:

Problem:

The index.yml is very often forgotten by people (even core contributors). Some people edit the manifest, some people edit the index, but 50% of the time one of them is forgotten. There's lots of metadata repetition, leading to maintainer and contributor mistakes.

Proposal:

  • Delete: index.yml (almost all of its fields are copy-pasted duplicates of the per-app manifests, causing a maintenance burden)
  • Add: meta.yml with the following contents, to tell Bottles which sub-directories to scan for *.yml manifests:
categories:
- Games
- Software
  • Modify <app name>.yml format as follows:
    • Name: Change this to be the "pretty display name" that used to only exist in the index, such as "GOG Galaxy". This field used to be redundant in the manifest and was always the same name as the manifest file minus the .yml extension (so for example, epicgamestore.yml had a Name: epicgamestore which is pointless and a source of potential typos). So let's instead track that internal "name" via the actual .yml filename, and use the Name field to carry the UI display name.
    • Category: Do not add this to the manifest. Instead, automatically detect it based on the name of the directory the manifest is inside, such as "Games" or "Software". That's one less source of typos.
    • Icon: Add this to the manifest. It's the filename of the icon to display during installation.
    • Event: If it's useful, add it to the manifest. I don't know the purpose. Only a few entries in the index currently have this value, and it's always a filename pointing at an installer file. It may be possible to just remove this entirely. Edit: Include it, I found its purpose and it looks like a great idea: https://github.com/bottlesdevs/programs/issues/414#issuecomment-3061658624
    • Hidden: Add this optional field. If missing, assume false. Otherwise allow the manifest to contain true/false here. If hidden is true, do not display this manifest in the UI. The purpose is to allow an easy way to hide broken manifests without having to manually move them out of the auto-scanned manifest directories.

The scanning process for the client to index all manifests is then as follows:

for category in categories:  # "categories" comes from meta.yml
    category_dir = programs_dir / category  # assumes pathlib.Path
    for manifest_yml in category_dir.glob("*.yml"):
        name = manifest_yml.stem
        # We have now automatically derived the category and manifest name:
        # category: Games
        # name: epicgamestore

        # Now read the manifest YAML file, and immediately skip the manifest
        # if `Hidden` exists and is `true`. Do that check before any other parsing,
        # to avoid trying to parse other possibly-outdated manifest structures.

With this repo structure, maintenance is only a matter of editing/moving a single .yml file per application.

Target: Bottles-Next, or possibly even the current public release. If targeting the current release, a simple migration solution is to put up a dummy index.yml file which is empty, so that outdated Bottles clients won't have any fatal errors and simply don't display any programs at all until the user has updated Bottles.

Dominant language
No language data
Stars
111
Forks
93
Avg merge
1d 1h
Merged PRs (30d)
3

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from bottlesdevs/programs

All issues in bottlesdevs/programs

Similar issues

More DevTools issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.