search

JohnTitor / ctest2

Automatic testing of FFI bindings for Rust
https://crates.io/crates/ctest2
Apache License 2.0
22 stars 20 forks source link

"this is a fork repo" text is somewhat confusing on crates.io page #18

Closed jnqnfe closed 3 years ago

jnqnfe commented 3 years ago

I discovered ctest2 on crates.io and I'm about to try it out. The readme text "Note: This is a fork repository and we intend to use this in libc-test only." is somewhat confusing appearing on the crates.io page.

  1. Firstly, from the crates.io perspective the page is not a repo so the sentence is not appropriate.
  2. Secondly, it's not really obvious who "we" is. Perhaps better to say "... and intended for use with libc-test ..."
  3. Thirdly, I failed to find anywhere what the purpose is of the existence of ctest2 over ctest. Although the text states only for libc-test, it's at the same time been published to crates.io with all the hallmarks of superseding the original (larger version number, '2' postfix to name). I'm sure that you can understand the confusion that causes; I'm looking into trying ctest/ctest2 for my own FFI crates and I'm left really not knowing which to actually use. Is the original broken currently and you were fed waiting for it to be fixed?
JohnTitor commented 3 years ago

from the crates.io perspective the page is not a repo so the sentence is not appropriate.

I usually expect the readme is on the repository page, this point feels quite pedantic for me.

Secondly, it's not really obvious who "we" is. Perhaps better to say "... and intended for use with libc-test ..."

I'm not an English native, sorry about that if it's consufing. If the statement is wrong, you can propose a better one with a PR.

Thirdly, I failed to find anywhere what the purpose is of the existence of ctest2 over ctest. Although the text states only for libc-test, it's at the same time been published to crates.io with all the hallmarks of superseding the original (larger version number, '2' postfix to name). I'm sure that you can understand the confusion that causes; I'm looking into trying ctest/ctest2 for my own FFI crates and I'm left really not knowing which to actually use. Is the original broken currently and you were fed waiting for it to be fixed?

I forked the ctest repo and tweaked the source to use libc crate's CI. And we don't guarantee ctest2 works just like ctest. Generally, you should use ctest, and if it doesn't work well, you can tweak the original source. You can also use ctest2, of course, but we cannot guarantee any behavior.

jnqnfe commented 3 years ago

from the crates.io perspective the page is not a repo so the sentence is not appropriate.

I usually expect the readme is on the repository page, this point feels quite pedantic for me.

Readme's obviously typically show up on both the repo and the crates.io page. They should be written IMO to make sense from both locations. Why would a crate author choose to let a readme show up on their crate's crates.io page if written only to make sense when read in the repo?

A simple replacement of "This is a fork repository" with "This is a fork of ctest" would suffice for it to make sense from both places. (Making the ctest reference a link to the original might also be nice in doing so).

Secondly, it's not really obvious who "we" is. Perhaps better to say "... and intended for use with libc-test ..."

I'm not an English native, sorry about that if it's consufing. If the statement is wrong, you can propose a better one with a PR.

Okay.

To clarify: After a little research I have noticed that you are listed as one of the owners of the libc crate, I did not know this before, and it is not at all obvious from the ctest2 crates.io page or repo. I presume now that you used the word "we" in reference to the group of developers of the libc crate. However, as I said, as a user simply coming across ctest2, whether the crates.io page or even the repo hosted within your personal github account, it is not at all obvious who you mean by "we".

It would make better sense as one of these alternatives:

An additional problem though is that reference to libc-test, which is not a crate published on crates.io and thus another point of potential confusion. I managed to find the libc-test crate within the repo of libc itself. It's not ideal to expect that people who encounter ctest2 will find libc-test so easily and thus discover what it is you're referring to.

Thus it would be best to replace "for libc-test only" as well, to have something like this:

"Note: This is a fork of `ctest`, intended for use in `libc` development testing only."

Thirdly, I failed to find anywhere what the purpose is of the existence of ctest2 over ctest. Although the text states only for libc-test, it's at the same time been published to crates.io with all the hallmarks of superseding the original (larger version number, '2' postfix to name). I'm sure that you can understand the confusion that causes; I'm looking into trying ctest/ctest2 for my own FFI crates and I'm left really not knowing which to actually use. Is the original broken currently and you were fed waiting for it to be fixed?

I forked the ctest repo and tweaked the source to use libc crate's CI. And we don't guarantee ctest2 works just like ctest. Generally, you should use ctest, and if it doesn't work well, you can tweak the original source. You can also use ctest2, of course, but we cannot guarantee any behavior.

This doesn't fully answer the question. In writing this response I ended up looking at the libc-test crate and discovered:

  1. A comment "# FIXME: Use fork ctest until the maintainer gets back." against the ctest2 dependency. So now I understand that ctest development has ground to a halt and you've been maintaining a fork to address some issues until work on the official ctest picks up again. If only you had just said so in the readme then things would have been clear!
  2. On the 1st of June you published your fork as ctest2 and pointed libc-test to it (a6920f9a5a9a835dc2bb4ba4347bb8a353ac30e6) rather than your private repo copy of ctest.

Additionally, I've just noticed that the authors of the original ctest are none other than fellow developers of libc. Which begs the question, why did you not get owner access from them for the actual ctest to take it over temporarily or permanently if they're too busy or AWOL?

I can understand you maintaining a separate repo with some improvements in the meantime, with libc-test using that rather than the ctest published on crates.io, but why did you then go and publish it on crates.io under a new name? I presume to help others use your improvements? But if you're expecting that ctest development will resume at some point or ownership will be transferred, then why publish your improvements as the misleading ctest2 with a greater version number than ctest, which suggests to people unfamiliar with libc development and otherwise what is going on, that ctest is truly dead and ctest2 replaces it, and not only causes confusion now, but even more later on if ctest does resume development leaving ctest2 dead. You could have just filed a bug report against ctest to inform people that develoment has moved temporarily to your private repo, with people pointing to that for the time being, using git tags for version pinning, or you could have called it ctest-libc to indicate that it is a variation of ctest rather than replacement. Or at very least the situation could be explained clearly in the readme.

It's a bit late for some of those alternatives now, just leaving the choice of clarifying things in the readme:

"Note: This is a fork of `ctest`, intended as a temporary replacement until maintenance of `ctest` resumes or ownership is transferred."

I'll file a PR.

BTW, both ctest and ctest2 proved useless to me in the end, since both fail with the same error relating to newer Rust syntax. :/ (I can't remember offhand what it was, I can re-run it to tell you if you want to know and consider fixing it).

Edit: Oh, I seem to recall the error related to it not understanding paths starting with crate::.