4 ms·

Maybe the only contributions that could be useful in this case is tests.

by yoz-y 5y ago

rbanffy 5y ago
Not even that is 100% sure. You still need to vet the tests. Documentation is also a good thing to add. The perspective of a fresh user is precious and only lasts so long. Documenting the onboarding process can point to documentation shortcomings that are great to fix.
- sumtechguy 5y ago
  I have seen a few big bang 'lets test everything' go horribly wrong. Where you were unsure if the tests or the code were broken. Test code is code. It needs to be reviewed too. It is also dead easy to go too far with it (I know I have fallen into that trap more than once).
  - quanticle 5y ago
    I would argue that the more pernicious result is tests that are correct and do pass at the moment they were written but are brittle, test internal interfaces and data, and generally ossify the design of the project because making any change now involves making the change and fixing the dozen tests the change breaks. It's hard to say no to those tests, because, on the surface they appear very thorough, and look brilliant on objective metrics, like branch/function coverage tools. It's only later, when every change, no matter how trivial, requires at least five or six files to be touched, that you come to realize the tarpit that you've ensnared yourself in.
    - yoz-y 5y ago
      On the other hand well written tests are awesome. When I have a pull request to review that makes change to a code I'm not familiar with, I always go to see the changes in tests first, to see what has actually changed on the interface level.
- yoz-y 5y ago
  Commenting on documentation and maybe updating is a good point yes. Onboarding docs can get quite stale. Both doc and test have the advantage of not breaking stuff for other users. Sort of, adding huge tests that make CI timeout or bogus doc is not ideal either. But at least both of those are on the starting path of understanding how the project works, which is a pre-requisite for contributing code.
  - rbanffy 5y ago
    The one thing we don’t need is teachers to dump students on us to assess their abilities by reviewing PRs.
- acuozzo 5y ago
  > Documenting the onboarding process I just want to add that this kind of documentation is worthwhile even for experienced developers. I've come across so many projects in my career in which the hardest task of all is figuring out where to start looking at the code. The entrypoint is often non-obvious and starting at main() often fails to elucidate the narrative of the program. To rectify this moving forward I've started keeping something of a development journal with new software I write. It's a cross between a README and a changelog and a sitemap; like printed MapQuest directions for my code.

Maybe the only contributions that could be useful in this case is tests.

by yoz-y 5y ago

Maybe the only contributions that could be useful in this case is tests.

Not even that is 100% sure. You still need to vet the tests. Documentation is also a good thing to add. The perspective of a fresh user is precious and only lasts so long. Documenting the onboarding process can point to documentation shortcomings that are great to fix.

sumtechguy 5y ago
I have seen a few big bang 'lets test everything' go horribly wrong. Where you were unsure if the tests or the code were broken. Test code is code. It needs to be reviewed too. It is also dead easy to go too far with it (I know I have fallen into that trap more than once).
- quanticle 5y ago
  I would argue that the more pernicious result is tests that are correct and do pass at the moment they were written but are brittle, test internal interfaces and data, and generally ossify the design of the project because making any change now involves making the change and fixing the dozen tests the change breaks. It's hard to say no to those tests, because, on the surface they appear very thorough, and look brilliant on objective metrics, like branch/function coverage tools. It's only later, when every change, no matter how trivial, requires at least five or six files to be touched, that you come to realize the tarpit that you've ensnared yourself in.
  - yoz-y 5y ago
    On the other hand well written tests are awesome. When I have a pull request to review that makes change to a code I'm not familiar with, I always go to see the changes in tests first, to see what has actually changed on the interface level.
yoz-y 5y ago
Commenting on documentation and maybe updating is a good point yes. Onboarding docs can get quite stale. Both doc and test have the advantage of not breaking stuff for other users. Sort of, adding huge tests that make CI timeout or bogus doc is not ideal either. But at least both of those are on the starting path of understanding how the project works, which is a pre-requisite for contributing code.
- rbanffy 5y ago
  The one thing we don’t need is teachers to dump students on us to assess their abilities by reviewing PRs.
acuozzo 5y ago
> Documenting the onboarding process I just want to add that this kind of documentation is worthwhile even for experienced developers. I've come across so many projects in my career in which the hardest task of all is figuring out where to start looking at the code. The entrypoint is often non-obvious and starting at main() often fails to elucidate the narrative of the program. To rectify this moving forward I've started keeping something of a development journal with new software I write. It's a cross between a README and a changelog and a sitemap; like printed MapQuest directions for my code.