Two days ago, I created an issue on Codebery issue list for a doc bug. Strangely, today, I found that the issue was deleted, and when I tried to re-create it, the system prompted to me that You cannot create issues in this repository because you are blocked by the repository owner.
What is the reason?
BTW, the doc bug:
https://ziglang.org/documentation/master/#Compile-Time-Expressions
> ... However, they can only be used in expressions which are known at compile-time, which is why the parameter T in the above snippet must be marked with comptime.
Now, type parameters are not required to be marked with `comptime`.
I think the results obtained from testing cannot replace the design intentions expressed in the documentation. There are many examples where tests in the current version pass without issues, but this only means that the current implementation allows it, and does not imply that doing so is correct according to the design intent. A typical example is referencing the lifetime of a position inside a block from outside that same block in a function. The current implementation allows this, but by design, the lifetime of a position inside a block ends once the block is exited.
Even if the typecomptime is omitted, I can still successfully pass tests in version 0.3.0 of Zig, but this description has always been in the documentation. Therefore, I believe the design intention is for users to always add comptime to such purely compile-time parameters, even though the current implementation does not specifically reject cases where it is not added.
If the OP has a large number of issue records attempting to modify the documentation based on their own personal testing, I imagine this approach could indeed be annoying to the maintainers…
Oh, I am sorry that my reply contained too much unfounded speculation. I think the problem lies in the issue itself, because it is raised based on an incorrect methodology, namely ‘designing documentation intent based on personal testing’. Such an issue may be considered a waste of the maintainers’ effort.
I’m sure you know this, but just to make sure, there’s no overlap between the Ziggit Mods and the Zig Core team. Just in case you were wondering why there hasn’t been much feedback on this.
Okay, let’s focus on the issue. I created this issue because I though this is absolutely a doc bug at that time. However, it looks it is not that simple. Do you think @npc1054657282’s explanation stands? Or should the doc need to be consistent with the implementation?
I tend to be kinda sympathetic to the response you initially got, namely: this is spam, yea, even unto bannability. Whether or not the comptime in a parameter like comptime T: type is optional or mandatory is not a bug, it is trivia; the current documentation does not cause people to write measurably worse code. In fact, I’d argue the opposite is true: even if comptime T: type is redundant, the comptime keyword performs a useful purpose, signaling that this function is generic and subject to monomorphization based on which values of T it is called with.
At times, I’ve contemplated submitting PRs for documentation “fixes”, but my hesitation has been twofold:
I’m guessing that with the pre-1.0 tumult, authors themselves mean to get in and augment and improve documentation, but not until the stop moving the rug under their own feet. I’ve thought, “when things are stabilized, and I see documentation that wants improvement, that might be the time to PR”.
I’ve wondered if the compute needed for all the ci checks is worth it for little documentation PRs. With plenty of mission-critical PRs going in, I’d hate to take up clock-cycles with smaller (albeit, sometimes ultimately pretty important) things.
With respect, I don’t think this is something people outside of the core team should be worrying about. Should that become an actual problem, it’s an indication that the CI configuration should be adjusted so that if only documentation is changed, then only documentation will be checked.
Additionally, aren’t CI jobs on PRs subject to manual acceptance? Or has that changed with the migration Codeberg?
That seems fair. While without a speck of doubt well-meaning, @zigo’s issue seems to be so minor to the point of being noise at this point in Zig’s development. As @alanza says, it is basically trivia, with basically no chance to mislead anyone into doing something wrong.
Perhaps the Docs here on Ziggit are a better place to spend that energy as a community?
Thank you for acknowledging that this was at most an innocent mistake. If doc issues are not currently being accepted, I suggest this needs to be communicated clearly, just as it was communicated that language enhancements are not being accepted. The decision of whether a doc issue is minor or major is not something the person filing an issue can accurately determine.
My experience on codeberg has been that the CIs are run automatically to move a submission from “checks missing” to “open”, prior to acceptance/rejection.
(Oh to be clear, I’m in no authoritative position here, super sorry if I came across like asserting something like that. Just voicing my personal opinion like the rest of the peers!)
