This is not my idea, an llvm Discord user "jjasmine" suggested it to someone asking how to get started:
im also a beginner but it's best to go through the llvm kaleidoscope tutorial first and try to shadow some good first issues, i.e repeat what the code author does and try to see for yourself why it works and maybe then you're ready for some first issues yourself
I think we could encourage this by deliberately working on some selected issues with this in mind. So that the issue itself has comments that document what approach was taken and why. This might fill in the gap between the issue content and the final PR, which only includes an explanation of the final changes, and even then, it may be very brief.
For example for a code generation issue, you might have "First I narrowed down the effected targets by trying a few triples" then include the commands. "I knew it must only effect 64 bit targets because...", but maybe "it turned out that this was misleading so instead I....". We could then collect links to these write ups in some place in the documentation, near where we suggest the "good first issue" tag.
A nice side effect of this is that although they could grow out of date, they will be linked to a time frame and hashes for before and after the fix. I think the principles shown would remain useful over time.
This is not my idea, an llvm Discord user "jjasmine" suggested it to someone asking how to get started:
I think we could encourage this by deliberately working on some selected issues with this in mind. So that the issue itself has comments that document what approach was taken and why. This might fill in the gap between the issue content and the final PR, which only includes an explanation of the final changes, and even then, it may be very brief.
For example for a code generation issue, you might have "First I narrowed down the effected targets by trying a few triples" then include the commands. "I knew it must only effect 64 bit targets because...", but maybe "it turned out that this was misleading so instead I....". We could then collect links to these write ups in some place in the documentation, near where we suggest the "good first issue" tag.
A nice side effect of this is that although they could grow out of date, they will be linked to a time frame and hashes for before and after the fix. I think the principles shown would remain useful over time.