Evaluate opportunities to ease the experience of new contributors

[kandersolar]

Is your feature request related to a problem? Please describe. We hear from pvlib users that unfamiliarity with git/github is sufficient to prevent them from making the jump from user to contributor. Ideally, sufficient documentation would exist to prevent this kind of procedural/tooling barrier from derailing contributions.

Our Contributing page our primary documentation to help people get started with contributing to pvlib. More generally, many resources for learning git/github and open-source contributing are available. Perhaps these guides are insufficient somehow, or perhaps people are not aware of them.

Describe the solution you'd like Evaluate where and how we can improve our documentation to make first contributions easier. Feedback from people who recently began contributing to open-source projects would be very valuable on this point.

Describe alternatives you've considered Some community members have suggested recording a video of walking through the process of making a first PR. I see value here, but it may be largely redundant with existing guides elsewhere on the internet, and also risks falling out of date if somehow the contribution process changes (an example: when we switched from master to main).

[Alia1999]

Instead of creating a new video, we could add link to existing youtube resources for how to create a PR for beginners? Additionally, for absolute beginners who have only used Github for browsing, resources for how to download git for desktop and use it would be helpful as well.

[kurt-rhee]

Hey team,

I am planning on posting this unofficial blog post once the PR for the transformer model gets merged. It outlines my personal workflow for stuff like this, and the workflow might be different than how other people use python since I am normally working in other programming languages, but my hope is that the more resources there are, the easier it becomes.

Open to any suggestions for things that are missing. I already know I should add:

• a link to the contributing page
• download of the flake8 extension for vscode

https://kurt-rhee.github.io/2024/06/13/how-to-contribute-to-pvlib

[RDaxini]

nice job with that post @kurt-rhee , I think the screenshots in particular are very helpful. I am a new contributor and at first (slowly getting used to it now) I found aspects of the git interface hard to navigate since there are a lot of symbols and terms to get to grips with. I think the definitions are super useful too --- any user can find them elsewhere from external pages but it's much easier and more convenient just to have them all in one place so that's good too

[echedey-ls]

@kurt-rhee as a fellow VSCoder, may I know what is the benefit of using the integrated Git? Does it change the opened files or so when you change branches? I got used to GitHub desktop before doing so much stuff in VSCode so I never bothered in switching to it.

Btw, that post is amazing. I may try to expand on other topics in the future: rST, sphinx-gallery or CI/CD so in the future we can gather all those posts in a pvlib wiki page.

[kurt-rhee]

@echedey-ls there is no benefit other than the fact that you don't have to leave the IDE to use it. I've used github desktop and command line in the past and I don't see any downsides to any of them except for maybe the steep learning curve of the command line for new users.

[echedey-ls]

Great. Thank you very much @kurt-rhee !!

EDIT: I found out that VSCode allows switching open files in the editor on branch change. It's amazing. CC @kurt-rhee

[RDaxini]

I think a definition of the good first issue tag and a link to such issues added to the contributing page to encourage new users to contribute. To be honest, I did not really know what this tag meant until I saw #2089 from @echedey-ls and the discussion with @AdamRJensen that concluded the issue could be left for newcomers. This would help people who want to contribute but don't have any ideas for PRs or aren't familiar with browsing through existing issues. Bear in mind if they are completely new to github, they are probably still working out what an issue and a PR actually is, so explaining this and directing them over to the good first issue tag might help.

On the subject of understanding definitions, the intro to the contributing code section is friendly and acknowledges how the overall process can be difficult first time round, which I think is good. However, the basics then jumps straight into talking about forking, cloning, committing, pushing, pull requests... I understand it's only an outline (a very efficient one at that, if you understand the jargon), and there are links to external pages later, but I think this could easily go straight over the head of the target audience (beginners*) and in itself be intimidating. I think a layman's explanation either preceding this, or embedded within it, would help. Something simple just explaining that there is an online version of pvlib, you send (fork) a version of that to your online account, copy (clone) your account's version to create a local version on your computer, make changes locally, upload (commit) those changes to the online version for review via a pull request. Not saying my lexical choice is optimal here in this comment, but just trying to giving a rough idea of what I mean. If I recall correctly, I think @kurt-rhee's blog post went some way in defining key terms, but I can't load the link now to check that(?)

*Beginner: I mean someone who can write straightforward scripts just for their own purposes such as data analysis, but they have limited-to-no broader coding experience, e.g. using GitHub, collaborative coding involving standards, documenting, testing, working with virtual environments... even just using the command prompt for anything other than conda install <package> or something along those lines

[echedey-ls]

After a brief conversation with @RDaxini and lurking his LinkedIn profile, I found that not everyone that wants to contribute here has ever used GitHub (or equivalent). I suggest that an starting point for the page should be an introduction to what it is and why it is used. And for unfamiliar users, recommend doing the GitHub hello world. My experience with that guide is that it is very useful for new people, as once I was, and other fellow students I have worked with.

[kurt-rhee]

Sorry @RDaxini, I updated the date of the post and that updates the post link. I have updated my comment above.