WAI Germany GitHub series
GitHub — when, why & how you should use it, too!
GitHub is an indispensable tool for anyone working collaboratively in a team on code. It is also highly recommended to use it even before joining a team, or working as data person in your day job. For people new to coding or data science, GitHub can even help you land your first data role.
So, while it is a critical tool, it can still be a big step for a newbie (like me) to get started on Github. Well, here’s the thing — you don’t have to take those first steps on your own. WAI Germany offers to help — with hands-on advice in this article, thanks to our GitHub pro Shannon Kehoe, as well as 1 on 1 feedback on your repository in our upcoming special event in early 2021. If you haven’t worked with Git or GitHub yet, now is a great time to start!
First steps
When you initialise your first project, you need to set up a repository over the online interface, as well as download & install the Github app for your local version. Once you set that up, here’s how you add & edit content:
Make sure everyone, everywhere works on the latest version of the project
Git pull → Git status → Git stash → Git add → Git commit → Git pushIf you are working in a team, make sure to get the latest version of the code before you continue working on it.
WAI Pros recommend: This can also be very useful if you are working on a project alone but you are using different hardware devices to work on!First, try Git status. If it is clean, this means everything on Github is up to date with your local repo (short for repository). If something red comes up with the Git status command, this means something was modified on the local repo. You now have different choices:
- Keep it/ commit the changes;
- Lose the changes;
- Or do something else.
If you don’t have local changes and want just want to get the latest version into your local repo from the remote one, use should use Git pull.
Git pull shows a +/- sign if something was added or deleted. Note that Git pull can pull changes from all branches, unless there are conflicts like changes done on different locations.
If you have local changes you are not sure yet what to do with them — e.g. if you want to commit them to the remote repo — you can use Git stash. This temporarily removes all changes so you can check something out on a different branch without committing the changes just yet.
One common reason why you might want to do this is that you first need to get rid of the changes so that you can go to a different branch, like the main branch — read more about branches further down in this article.
Remember: Git stash is not committing.If you later decide that you want to commit all of the changes that you have stashed away, you can do so with Git stash apply. Else, you can use Git add to select which of your changed files you want to put in line for a commit, while holding off from others. Those files will then be shown in green in the Git status staging area. To directly commit a single file, you can also use the command:
Git commit -m “file name”.Once you have committed one or more files, you can visit Git log which shows an overview over the committed content. At this point, the commit hash allows you to go back to an earlier version if you want to.
Finally, when you have checked and are happy with the commit, Git push will take your local commit into the remote repository.
Branches
Github offers you the opportunity to showcase your work — be it for teammates or potential employers — in different states. For your code that is working as expected, use the Main branch (more on this later).
Everything else you should develop on another branch. You can add new branches to your repository by typing:
Git branch “name”Best-practice-examples for using other branches are trying out a new idea before committing it to the Main branch, or storing stuff, ideas, and work in progress.
If you — like me — are hesitant to make your unfinished work public, you can think about this as a transparent way to show what you are currently working on and to give others a good idea about how you approach a problem. Not to forget, your unfinished work — and even your mistakes that you abandon later on — could inspire others. Everyone can learn from other peoples’ mistakes.
→ WAI Pros recommend: You can use other branches to keep examples of how not to do it. Make good use of commenting in this case! This shows that you learned something and explains why you have done things in certain ways.(Of course, you can also just delete a branch once the problem is solved.)
Best practice for GitHub repositories
If you are looking for a new job, be advised that hiring managers often look at a candidate’s GitHub repository to get an impression of the candidate’s interests, experiences, and coding skills. They also often use a candidate’s GitHub repository as a starting point in an interview since talking about work they are very familiar with eases up the candidates and it can be a basis to start discuss how they are thinking, what features they would like to develop if they had more time, or if they can explain was they were doing.
What & when to commit
Just like me — you may ask yourself, what you can commit, and at what stage of the work? This has admittedly been one of the biggest hurdles for me so far.
Remember, you can use your GitHub repository to give others insights in how you think and work. Not everything you commit and push has to be a finished, polished product, but here are some pointers what you can feel confident committing:
- Everything in the Main branch should work, but you can use other branches to work on new features. You can e.g. use branches like deployed/ development for your work in progress.
- It doesn’t have to be done to be shown. But the parts merged into the main branch have to work with minimal errors and should have a core functionality that shows what problems you are solving.
- When you have to decide if you merge something into the main branch, it may feel a bit like writing an essay — you can always make it better, but at some point you have to turn it in.
- If you are still undecided if you should commit something or not, maybe this idea from Scrum can help you decide: if it is a potentially shippable increment and can get data/ user feedback, you can commit it to the main branch.
Remember: It’s all about getting better, it doesn’t have to be perfect. Just like in real life, you can use your GitHub projects to fail, learn, and repeat.Good code/ good practice:
In many ways, you can think of your GitHub repository as your calling card for your coding career. So, if you are looking for a new job, you may want to tidy up your repo a bit to leave a good first impression. Here are some recommendations from WAI pros (some are also acting as hiring managers) what you should check for:
- First things first: Rename your Master branch to Main branch as a matter of political correctness.
- All classes and functions should have doc strings that clearly state what they do, which arguments they take, what data they are taking in, and what they return.
- Every file also should have metainformation, including the author, the date it was started, and a description if you have multiple classes in a file.
- You should also write down all libraries that you use in the requirements file (.txt) so everyone can install all libraries needed to run your code with:
pip intall -r requirements.txt If you are actively job hunting, and you want to do some tidying up in your GitHub repo, WAI Germany offers a workshop where seasoned professionals will give you individual feedback on your repository (scheduled for early 2021). So, if you want to benefit from free, individual advice, now is the time to get started with your repository to prepare for the workshop!
→ Follow https://medium.com/wai-germany or subscribe to our newsletter (under https://www.womeninai.co/) to stay in the loop!
