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.

#Filing issues

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 ~cnx/ipwhl@todo.sr.ht 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: ~cnx/ipwhl-devel@lists.sr.ht.

Higher-level design issues shall be discussed on the discussion mailing list: ~cnx/ipwhl-discuss@lists.sr.ht.

#Sending patches

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.

#Setting up local repositories

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 "~cnx/ipwhl-devel@lists.sr.ht"
  git -C $repo config format.subjectPrefix "PATCH ipwhl-$repo"
done

#Making changes

#Improving documentation

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.

#Hacking utilities

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!

#Updating metadata

First, install the ipwhl utilities, either directly from source or using your package manager, and cd data.

The mainline metadata Git repository includes the wheels declarations in pkgs and the supported platforms in SUPPORTED. Inside pkgs each project is prefixed by the smallest 8 bits in lowercase hexadecimal of the sum of its characters, which can be generated using ipwhl-prefix $project, where $project is the concerned project name.

Presuming you are trying to add the declaration for a wheel from $project 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 ipwhl-declgen. Either way, at first the wheel must be downloaded (let's say from $url) and passed to ipfs add --only-hash for the CID, then the METADATA file 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 as $declaration.

ipwhl-declgen $url pkgs/$(ipwhl-prefix $project)

Floating cheeses declarations must satisfy various requirements, which can be checked automatically:

ipwhl-nameck pkgs
echo $declaration | ipwhl-declck
ipwhl-depsck pkgs < 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.

#Requesting reviews and responding to feedback

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 main branch 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.

#Participating in discussions

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!