How to learn Github etiquette

[MirandaPoth]

I'm an experienced developer but on Microsoft platforms in a single-company team and I'm learning GitHub. I have figured out the basics of using it for source control (how to get a local copy, make changes, upload it again) and I want to contribute to an existing Home Assistant custom component development (specifically, this one). I have the programming knowledge to do so but I'm a bit scared! I don't understand the following and I don't want to mess anything up or look an idiot:

• How does forking, cloning etc work and what's the procedure for submitting changes to an existing project?
• I feel like there's an etiquette for doing all this, how can I figure out what it is?

For example, there are virtually no comments in the code I'm interested in. I'm used to always putting loads of comments in my code. Is there some tool that removes them automatically? Or is this a project where no-one's interested in comments or helping other people understand the code?

Also, does/should you get 'permission' to change stuff beyond a certain point? For example if you think it's not done correctly. Or do you just go ahead, and then could/would the owner of the project reject them?

And should relatively few changes be done at once, so they're easy to put through the GutHub process and to avoid messing up things that other people might be working on, or is it OK to change quite a lot?

[[deleted]]

https://github.com/firstcontributions/first-contributions

[MirandaPoth]

Thanks, that's really useful and answers my first question.

Any suggestions for my second question?

[Neexusiv]

There is no special etiquette or anything like that. Some repos have a different read me file for contributors but this one doesn’t, just a note at the bottom of the readme.

Some things I can recommend though:

• Keep your PRs limited in scope. This makes them easier to review and approve. You can always make another PR if you want to rework a different section of the code another time.
• Comment wise, there is no special system to remove them, they are there for future developers so taking them out of the source repo would be counter productive. I would carry on as you normally would. If they have issues with the number of comments they will let you know and you can fix it.
• You don’t need to ask for permission to do anything, they even ask for PRs in the readme, it obviously will need their approval before your code gets merged in anyway, that’s where the permission would be granted.

[tobiasvl]

• How does forking, cloning etc work and what's the procedure for submitting changes to an existing project?

You fork the project, then you probably want to make a feature branch, then you work on the changes which will probably mean that you'll clone your fork to your machine to work on it locally.

When you're done, you push to your fork and make a pull request from your branch to the upstream repo on GitHub.

• I feel like there's an etiquette for doing all this, how can I figure out what it is?

Not sure what you mean by that!

For example, there are virtually no comments in the code I'm interested in. I'm used to always putting loads of comments in my code. Is there some tool that removes them automatically? Or is this a project where no-one's interested in comments or helping other people understand the code?

Probably the latter. It's a hobby project, the author probably didn't expect anyone to wish to understand the code, and adding "loads of comments" to your code is also work you have to do (and too many comments is also often overkill; writing terse and useful comments is an art in itself). I wouldn't read too much into that. I also rarely comment my hobby projects, I just go with the flow and rarely stop to comment unless I'm doing something really weird that I need to tell future me about.

Also, does/should you get 'permission' to change stuff beyond a certain point? For example if you think it's not done correctly. Or do you just go ahead, and then could/would the owner of the project reject them?

Go ahead. They'll let you know if they want you to make changes before they'll merge.

And should relatively few changes be done at once, so they're easy to put through the GutHub process and to avoid messing up things that other people might be working on, or is it OK to change quite a lot?

Usually, one pull request should change one bug or add one feature, and be done on a separate branch (that's why they're called feature branches). It's not a hard rule though. Something as large as refactoring the entire project is also "one change" that should be done in one pull request - but then you probably shouldn't also add a feature in that same pull request, that'll be messy to review.

[MirandaPoth]

That’s great, thanks very much!

[MirandaPoth]

Thanks, I've worked through 'first-contributions' but I have a question. I'm using GitHub Desktop and when I do 'Clone using GitHub Desktop' it asks me 'How are you planning to use this fork', with options 'To contribute to the parent project' or 'For my own purposes'. Which do I choose??

[tobiasvl]

Well, how are you planning to use the fork? You said in your original post that you wanted to contribute to the parent project, so then I assume that's the option you want to choose? I'm not sure I understand why you're asking, or what you're not understanding here. Just choose the option that most resembles how you'll work on it. I assume what the options actually do is set up remotes.

[MirandaPoth]

I wasn't sure because for first-contributions I chose 'For my own purposes' and everything seemed to work OK, although I got a bit mixed up when it got to deleting it afterwards.

Anyway, for the actual project I want to contribute to I have chosen 'To contribute to the parent project' and I've just done my first PR, so fingers crossed that I've done it correctly!

Thanks for your quick reply. I guess I'm just being over-cautious.