Continue to update the Problem-Reports article.
This pass attempts to get rid of dead links. In addition, some other wrong information is fixed.
This is one in a continuing series of fixes to this article.
Note: I have not yet build-tested it.
Details
Details
Diff Detail
Diff Detail
- Repository
- R9 FreeBSD doc repository
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
| documentation/content/en/articles/problem-reports/_index.adoc | ||
|---|---|---|
| 80 | I cannot endorse telling people to consult the discord under it's current administration. | |
| documentation/content/en/articles/problem-reports/_index.adoc | ||
|---|---|---|
| 102 | Well, it is a Frequently Asked Question. It used to be in the FAQ but now it isn't. I won't object if we just s/FAQ// . | |
| documentation/content/en/articles/problem-reports/_index.adoc | ||
|---|---|---|
| 144 | Hmm. I don't know, but it seems to be setting it automatically. | |
Comment Actions
I think it's basically fine.
| documentation/content/en/articles/problem-reports/_index.adoc | ||
|---|---|---|
| 120 | and mailing lists? | |
| 144 | If don't see that, click "Show Advanced Fields" on the top-left of the submitting new bug interface. Then in the "attachment" section, there is "Content Type: If the attachment is a patch, check the box below. [ ] patch" This is very useful as it will mark the patch's mime type as "text/plain" which can be viewed in the browser correctly. | |
| 145 | Indeed, and not sure if we want to mention that the patch generated via git format-patch will be detected as application/mbox automatically, this is hard to say a bug in the system as it's indeed a valid mbox format, but it's much better to be attributed as text/plain to be easier to review. | |
| documentation/content/en/articles/problem-reports/_index.adoc | ||
|---|---|---|
| 102 |
Come to think of it, I'd make the whole clause "first read the extref:{handbook}/cutting-edge/[Handbook section on Versions]" (if that's indeed the section you mean). | |
| documentation/content/en/articles/problem-reports/_index.adoc | ||
|---|---|---|
| 120 | Well, the line just above it is about the mailing lists. | |
| documentation/content/en/articles/problem-reports/_index.adoc | ||
|---|---|---|
| 145 | Is *that* where that bug is. It has been driving me nuts. | |
Comment Actions
I found some tweaks build testing (via cd doc && DOC_LANG=en make documentation && w3m documentation/public/en/articles/problem-reports/index.html):
- the handbook link on 117 was still dead, so I changed that to just the top of the handbook
- there were some apostrophe's that seem like they should be backticks
Since these seemed trivial I committed them with these fixes. Sorry for the delay!
| documentation/content/en/articles/problem-reports/_index.adoc | ||
|---|---|---|
| 194 | I know it’s late to comment on this review — the change has already been committed. Still, I’d like to suggest a small improvement for the future, because I think the current wording is a bit misleading (and I only really noticed it when I started translating it into Russian). The advice itself is correct, but the phrasing could be clearer. It currently says to base a patch at the base of the tree, which is confusing. In Git, “base” isn’t really an official term for the tip of a branch — it’s more about the commit a branch diverged from (like in merge-base or rebase). When we rebase, we actually move our branch to the head of another branch — that becomes the new base, but it wasn’t the base before. Please base your patch(es) at the head of the appropriate tree. That feels more accurate and less likely to confuse someone reading it for the first time. | |
| documentation/content/en/articles/problem-reports/_index.adoc | ||
|---|---|---|
| 194 | I see your point. However, what I really want it to say is "the highest point in the tree, e.g. under /usr/src/ or /usr/ports or /usr/doc". Saying "head" to me sounds ambiguous with "latest commit in that tree". Does that make any sense? I would just like it to be as unambiguous as possible. | |
| documentation/content/en/articles/problem-reports/_index.adoc | ||
|---|---|---|
| 194 | Ah, now I see where I got confused — thank you for clarifying! I completely missed that the last sentence was specifically about the diff part, not about git format-patch (base sounds similar to rebase). You're absolutely right: in that context, "base" clearly means the root of the working tree (like /usr/src), not a Git branch tip. Your explanation makes perfect sense, and I agree that "head" could indeed be misinterpreted as the latest commit (I thought about rebase). So the original wording is actually correct as is — my mistake! That said, if you ever want to make it even more explicit, maybe something like: Please base your diff at the root of the appropriate tree (e.g., /usr/src). But honestly, your current version is clear enough once you read it carefully | |