First of all, thank you for using and contributing to floating cheeses! We welcome all forms of contribution, and the mo the merrier. By saying this, we also mean that we much prefer receiving many small and self-contained bug reports, feature requests and patches to a giant one. There is no limit to the number of contributions one may or should make. While it may seem appealing to be able to dump all thoughts and feelings into one thread, it would be more difficult for us to keep track of the progress.
An issue could range anywhere from a bug report to a request for feature or wheel update and can be filed against our ticket tracker either via email to ~email@example.com or through the TODO web UI. Although the later is only available to sr.ht users, there is no difference in functionality.
Note that the TODO tracker is only for tracking TODOs, i.e. issues that the maintainers want to see solved. When it is uncertain if this is the case, one should instead start an discussion on the development mailing list: ~firstname.lastname@example.org.
Development of mainline IPWHL is carried out on SourceHut, which builds itself around emails, as showed above with ticket tracker and discussion platforms. Code collaboration is not an exception: patches shall be sent to the development mailing list as well.
Since the metadata declarations are checked using the scripts in the utilities repository, it is recommended to keep both in a common directory:
mkdir ipwhl cd ipwhl
For convenience purposes, let's place the documentation repository under the same parent directory. The following shell snippet will clone and set up all three mainline Git repository for sending emails the development mailing list with appropriate subject prefixes.
for repo in docs utils data do git clone https://git.sr.ht/~cnx/ipwhl-$repo $repo git -C $repo config sendemail.to "~email@example.com" git -C $repo config format.subjectPrefix "PATCH ipwhl-$repo" done
The document has plenty of rooms for improvement—you can help by pointing out errors, organizing for more readable structure, or adding some useful instructions.
For portability, the utilities are written in Python and only depend on two libraries, packaging and toml, which can be installed via from your operating system, IPWHL or PyPI (in that order of preference).
Static code analysis is automated by tox:
tox -c utils
At the time of writing, tests are lacking. You can be the first one to add some!
The mainline metadata Git repository includes
the wheels declarations in
pkgs and the supported platforms in
pkgs each project is prefixed by the smallest 8 bits in lowercase
hexadecimal of the sum of its characters, which can be generated using
utils/prefix.py $project, where
$project is the concerned project name.
Presuming you are trying to add the declaration for a wheel from
which is available on the cheese shop, you can find the direct URL
to the wheel on
https://pypi.org/simple/$project. The wheel needs not
be on PyPI though, the URL pointing to it only have to be accessible
by our maintainers and CI service, i.e. publicly reachable.
If upstream only provides source distributions, you can build the corresponding wheels, host it somewhere and link to there. This process must be transparent, e.g. done on a reputable CI service. It is, however, still preferable to urge the upstream maintainers to upload the wheels to a platform with clear authority.
Once you have obtained the wheel URL, you can manually declare according
to the specification or make use of
Either way, at first the wheel must be downloaded (let's say from
and passed to
ipfs add --only-hash for the CID, then the
must be extracted to parse the requirements. The script automates this
and can be executed by the following command, printing to standard output
the path to the newly generated declaration, which we shall refer to
utils/declgen.py $url data/pkgs/$(utils/prefix.py $project)
Floating cheeses declarations must satisfy various requirements, which can be checked automatically:
utils/nameck.py data/pkgs echo $declaration | utils/declck.py utils/depsck.py data/pkgs < data/SUPPORTED
Common errors include a project's wheels being installable on a same platform and missing and/or conflicting dependencies. Both require removing, adding or replacing other declarations, often recursively, and thus might require a substantial amount of work to resolve. Worry not, you can always reach out for help on the communication channels, where our maintainers and contributors ran into similar problems will be happy to offer their help!
Sometimes, the overall change can involve dozens of declarations. In that case, it is best to send multiple independent patches to not overwhelm the maintainers reviewing your contributions.
Please keep each patchset small and self-contained. In other words, they must never depend on each other but you should also split them wisely. In addition, try to arrange the commits in a patchset in an order that every point in the history is a valid state.
It is advisory to rebase the patches on top of the latest
before sending them to the mailing list to iron out the merge conflicts.
If you have managed to do so, simply run
git send-email main
This assumes that you already have appropriate local Git configurations
as shown above, in addition to
git send-email correctly set up.
git-send-email.io is an excellent guide to get you started.
It also contains the instructions on dealing with feedbacks from maintainers
and some useful tips.
Since the floating cheeses are made by volunteers, recurring contributions are incredibly valuable. If you want to stick around, you are more than welcome and we recommend you to subscribe to the announcement and discussion mailing list to keep track of and help decide the development direction, as well as troubleshooting users' issues.
Contributors with a larger time pool can also join the development mailing list and help reviewing patches. You can even self-promote to become a maintainer!