GSoC feedback on the pvlib contribution process

[AdamRJensen]

This issue is for the 2024 cohort of GSoC students to document challenges related to contributing to pvlib.

The aim is to learn about the challenges that new contributors face, and hopefully be able to make changes to make the process easier.

2024 GSoC students: @echedey-ls, @IoannisSifnaios, @RDaxini
Mentors: @kandersolar, @AdamRJensen

[IoannisSifnaios]

I think I am missing some documentation guidelines. E.g., when a parameter in a function is unitless, how to you denote that? Right now, I found three different ways: [-], [unitless], or nothing.
[Adam] - we should make a template function that showcases our preferences in how to write a function, e.g., function name, units, etc.

[echedey-ls]

cross-referencing #2205 for whenever we come back to this

[cwhanse]

I prefer [unitless] but I don't think we've made a consensus choice.

@pvlib/pvlib-core your vote? [unitless], [-] or nothing?

[IoannisSifnaios]

Again, regarding documentation... how do we write the references? (e.g., how many authors, when do we use et al., do we put the year in parenthesis or not, how to report the journal issue and pages)

[echedey-ls]

cross-referencing #2202 for whenever we come back

[RDaxini]

Setting up the blog was a challenge. Beyond the initial steps that were provided , there were a lot of additional steps required with other files in the different folders needing updating and various settings changing. Hard to recall the details exactly since I got a bit lost, but @AdamRJensen saved me (thanks for your help again). I know in the end I was forking a different repository to that which you had advised (yours instead of Ioannis's), but even when I started initially with forking Ioannis's I was still running into similar issues (just maybe fewer overall).

In terms of knowing what files to update and where, this came up for me when I tried to write my first piece of code too. When I wanted to write a new spectral correction function, I first thought I had to do it in a separate file, then that would get merged into mismatch.py. Same for the unit tests and test_spectrum.py. I also found later that I needed to update other files such as __init__.py, then for the docs there was spectrum.rst, and so on. All of this was very straightforward once I'd been told, so it's not technically challenging, but maybe some advanced guidance would be helpful because otherwise it's easy to feel a bit lost at first when all you see is that what you did simply doesn't work and you can't fathom why. This is not GSoC specific I guess, so it might overlap with this issue from @kandersolar #2067