Forem: Lauren Stephenson

How to organize your school projects on GitHub

Lauren Stephenson — Mon, 31 Aug 2020 22:16:17 +0000

Cover Image by Memed_Nurrohmad from Pixabay

Whether you're doing your own lesson plan as a self-taught programmer, attending a bootcamp, going to a college, or are in any other learning situation, it's important to stay organized and keep track of projects you care about or need to submit.

How you choose to organize your projects is up to you. I'm in my final semester of college, and I've seen it done in a variety of ways. I also see this question asked online occasionally, and it's one I asked before too. There are a few good tips I've learned, and I thought I'd share them in a short post.

I currently keep my projects in GitHub repositories and will refer to that method in this article, but you can check out some good alternatives here as well.

Public vs private repo

Hands down, you want to make your GitHub repository private.

Typically, other students are also in the class working on the project at the same time as you. If you make your repo a public one, that means everyone can see your code. That includes your classmates.

Many, many, many professors and teachers will say that if someone else uses your code, you are also at fault for letting them have access to it. Doesn't matter if you intended for it or not.

Even when the class is over, I wouldn't recommend making it public. Future students may copy the code, and that serves no good purpose.

Plus, your class may have some special rules about whether you're allowed to make certain code public or not. It's always best to err on the side of caution and keep the repo private.

If you want to show someone your code, you can always share it with them privately. A simple way to do that would be to send them the project in a zipped file via email or on the cloud (OneDrive, Google Drive, etc). If you need to work with a partner on a project, you can add them as a collaborator and that will let them access the private repo.

One course per repo or one project per repo?

Should you make one GitHub repo for each programming class? And then store every project in that repo?

Or is it better to make one repo for every project?

Again, it's really up to you. You could try both out and see which
one you like more.

Here are a couple of pros and cons for using one repo for one class, with a sub-folder for each project.

Pros	Cons
All the code for your class is in a single location.	Harder to use the GitHub search feature for an individual project. If you search for a particular phrase, any relevant results will appear, possibly for multiple projects. This can make it harder to navigate the results.
Quickly refer to the other files when working on a project in your code editor.	If each project is a stand-alone project, and especially if they are unique to each other, then it may not make sense to keep them together in one repo aside from the fact that they were part of the same class curriculum.

I usually prefer to make one repo for every project. It feels more organized to me that way, generally speaking.

But I have used a single repo to keep multiple projects that were part of the same class a couple of times before. In those cases the projects were either building on top of the same code (so really it was one project split into multiple), or they were just very closely related so it made sense from an organizational perspective to me.

The README

Always include a README. If you have one repo for each project, then you should have one README for each of them.

If you have one repo with multiple projects, I'd suggest a main README for the repo as well as one README inside each project folder.

The main repo could just have the basic description of the class or types of projects, and you could even have a section that describes each project with a link to that project folder.

README basics

Don't get stuck on trying to make your READMEs look perfect. Remember, you can always add onto them later. For now, just include the most basic essentials.

It may depend on your project, but generally you will want the following in your project README:

Project description
How to run the project
Any special requirements to run it

As you work through the project or towards the end, you can add other features too. Screenshots are wonderful to include, or examples of using the project or what the output will be, and if necessary what it means.

Since it's a private school project, you will probably be the only person to ever see the code. However, keep in mind that you may want to show someone your work later on (like when applying for a job). Even if you are the only person who will ever see it, it is still a good idea to document the project as if someone else may eventually see it or work on it.

Writing a good README will become easier as you get more practice. Another nice thing is that after you have a README for one project, you can always copy that file and use it as a starting point for future projects.

You can even use a README generator such as this one if that makes it easier for you. For private school projects though, this probably isn't needed quite as much.

README usefulness

You might not think you need a README at the time of working on the project. After all, you're well aware of how to run it while you're actually working on it. However, it may prove to be very helpful to you later on.

Maybe months later you will be working on something else, and realize that you have a problem similar to one you experienced in a past project. So you want to look at it again.

Well what if there is no README? You'll have to remember which project it was (perhaps solely based on the repo title) and how to run it. Even if it seems obvious to you at the time, it may not be obvious at all after you've moved on from it.

README template

If you don't have any READMEs to go off of yet, I have a couple of resources for you. One is a list of awesome READMEs. This is a great source for inspiration.

You can also copy the snippet below into a README.md file as a basic starting point.

# Project Title

> Short description of project.

## Quick Start

1. Clone or download the repo
2. Run `npm install`
3. Run `npm start`

If you need a cheat sheet for markdown (used for formatting README files), there is a great resource for that here.

Conclusion

How you organize your school projects is ultimately up to you. You should do whatever will help you be most successful! That can look different from person to person. If you aren't sure what that looks like for you yet, don't worry. Just try out things you think might be good, see how you feel about it, and make changes as needed.

Just remember to make your school repos private and always include a basic README file. You'll thank yourself later!

This article was originally published on my personal website's blog, Joy Bytes.

Lessons learned as a software intern during a pandemic

Lauren Stephenson — Sat, 01 Aug 2020 21:53:35 +0000

Interning is tough enough even when there isn’t a pandemic. I feel for every person who has had to stress over the well-being of their loved ones or worry a lot for their own health and safety. I’ve been extremely fortunate in that my level of pandemic-related stress has probably been average, or maybe even below-average.

I just want to say that for anyone who has had to deal with a high amount of stress because of this pandemic, or any reason really, you’re not alone and it’s okay if you feel like you aren’t excelling as much as you would under regular circumstances. I’ve dealt with stressful situations and I know that sometimes just getting through the work day or school day is an accomplishment in itself. It’s hard to give it your all when you’re already dealing with so much as it is.

I've been lucky to be able to spend time this summer focusing a lot on my internship, and what I want in my career. I'm lucky to have had a strong support system to help me as I navigated my virtual internship too.

Everyone who helps run the summer internship program at Cerner has been absolutely amazing and gone out of their way to help everyone succeed. They provided guidance and helped us all navigate our virtual internships.

I also had a ton of support from my team, other associates at Cerner, and some wonderful friends. They know who they are and I will be forever grateful to each of them.

At the end of the day, I think having a strong support system and others who can help guide you is one of the best things for your career or any other major endeavor.

Being an intern in a virtual setting has really made it clear to me that my career is truly in my own hands. Even from the first day of work, it was clear.

It was up to me to login and figure out how to set everything up so that I could make it to that first day of training. Once I had my first real task to do, it was on me to get it done.

That’s true even under regular circumstances. But when you’re alone in a room all day, it feels more apparent. There was no one to physically stop by my desk and check in with me.

If anything, I think working remotely made me even more determined to do well. The last thing I wanted was for anyone to think that I wasn’t giving it my best effort.

If people couldn’t physically observe me working, then I needed to make sure that they saw it in the work I was pushing out.

I think success is something that looks different for everyone. What you want to prioritize is up to you and can change over time, and that’s the real beauty of it. For me, I’ve been studying for years to become a software engineer and I’m beyond excited to be so close to reaching that goal. With this being my final internship and only one more semester to go, I’ve felt easily motivated and eager to make as much progress as I reasonably can.

For me, my focus is currently on my career. And I've been lucky to have a ton of inspirational people to learn from at this internship, including other interns. I’ve seen people accomplish some amazing things this summer, and it has definitely inspired me.

Being committed to doing good work and finding ways to make valuable contributions helps everyone, including yourself.

Everyone make mistakes sometimes. I know I did. But I think at the end of the day, if you're putting in effort, have a positive attitude, and can learn from those mistakes, you'll do great.

All that said, it was also critical to know when to take a break and prevent burnout. It’s easy to lose track of time when there’s no physical disconnect between work and personal life. Living in a small apartment also meant that I couldn’t have a whole room dedicated to doing just work.

I also learned that I actually feel better when I can move around occasionally. Whether it was doing some work on the couch or sitting outside when the weather was nice, sometimes a change of scenery was surprisingly helpful.

Working remotely has its perks. There’s no commute. That’s the best perk in my mind. I’ve saved an impressive amount of time and money by not having to drive to and from work each day.

It also has some pitfalls to avoid. Like making sure you aren’t all alone when you’re working. It’s easy to just spend the day doing work and going to meetings, but not talking to anyone outside of that.

Normally you could walk down a hallway or step into the break room and talk with people. Or stop by someone’s desk to have a quick chat. That just isn’t a thing in remote work.

It was also important to keep in mind that this was not the typical situation for remote work.

Working remotely during a pandemic is not going to feel the same as it would under regular circumstances. So keeping an eye on how I was feeling and making sure I was doing okay was crucial.

I learned how to reach out to people. Whether it was a teammate, a fellow intern friend, or someone else I’d met virtually. It could be about work, or maybe we would just catch up for a bit. It was nice to just chat occasionally, like you would if you were working in the same building.

One of the best things the summer internship program involved was the Friday “lunch roulettes”. Every Friday we were assigned a new group and we could meet up to get virtual lunch together.

I was able to meet lots and lots of other interns this way, and it was a blast. I even met with a few interns on other days of the week to do our own lunch get-togethers, and it was awesome.

I also met a lot of people just through virtual chatting and through special events, like at the ShipIt hackathon and the DevCon conference.

I wasn’t sure if I would make any friends in a remote setting like this, but I was pleasantly surprised to meet a lot of great people who I hope to stay in touch with even after the internship is over.

I'm grateful to have had an internship at all this summer, and I'm especially glad that it was with Cerner. Making healthcare better is something that I find extremely meaningful, and I'm proud to have made some contributions to that through this virtual internship.

Tomorrow is my last day, and even though everyone warned me it would go by fast, I’m still shocked. It may have gone by fast, but I’ve learned a great deal. I don’t know exactly what my final semester of classes will look like, or how long I’ll continue to do work remotely. But I know that this internship has made me more than prepared to adapt and take on whatever comes next.

This article was originally published on my personal website's blog, Joy Bytes.

10 tips for maintaining an open source project

Lauren Stephenson — Sat, 01 Aug 2020 21:40:08 +0000

Cover Image by Tumisu from Pixabay

Becoming an open source project maintainer is as easy as creating a public repository on GitHub, or on any other open source hosting services.

But what can you do to make sure you're being a good maintainer?

If you're familiar with contributing to open source, you probably have an idea of what a beginner-friendly repository looks like.

A lot of these tips are things that benefit new project contributors, but all of them are things that improve the experience for everyone.

Here are a few things that I've learned, both as a maintainer and as someone looking to contribute to other projects.

1. Choose a license

This is easy to overlook. You might think, who cares? My project is small, and I don't care what people do with my code.

Well, a license doesn't just protect you or your project.

It gives people confidence in using and/or contributing to your project.

I've seen people online say that if your project doesn't have a license, they won't contribute to it or use your code in any of their work.

If the rules aren't clear, why risk getting involved?

Visit choosealicense.com to quickly and easily find out which license suits your project best. Having a license is a best practice. Don't skip this step!

2. Add documentation

This is absolutely critical if you want anyone to contribute to your project.

Nobody is going to bother with your project if you don't even have a README.

Think about it. When you look at other people's projects, what's the first thing you look for? You look for written information, right? Anything that tells you what you're looking at, what it's for, how to use it.

Make it easy for people to find the information they want. A good README goes a really long way.

Whenever I need some inspiration, I scroll through the Awesome README repo. Definitely check it out for some fantastic content and layout ideas.

Finally, go to your GitHub repo, click on the "Insights" tab, and click on the "Community" tab.

This shows a list of common documentation you should have. The more of these things that you have, the friendlier your project will appear to potential contributors.

Including these pieces will make it easier for people to start contributing. It will also lay out the ground rules to help you maintain a productive and positive community. Nobody wants to be in a toxic environment.

3. Create Issues for each task and label them

Create the Issue

When you know of a bug or feature that needs to be worked on, make a GitHub Issue for it. Encourage others to create Issues as needed.

If you followed step 2, you should have Issue templates for people to use. These are helpful for you as well!

Fill out the Issue with enough information so that someone could look at it and know if it's something they'd be interested in taking on.

Add labels

Don't forget to add labels to your Issues. These can provide a lot of information at a quick glance.

Is this Issue beginner-friendly? Is it being worked on by anyone yet? Is it a bug or is it a new feature?

Help people find the answers to these questions quickly by using labels.

4. Share on social media and any relevant websites

Image by William Iven from Pixabay

Social media is a fantastic place to learn from different perspectives, meet other coders, and share your project with potential users.

Look for places that would be relevant to share your project, and follow their posting guidelines. Try not to post it so often or in such a way that it comes off as spam.

You could tweet about your project, post it in various communities on Reddit, even share it on Instagram. You can bring it up in comments wherever it's relevant.

You can also change up the reason behind posting. You can share it just to let people know about the project. You can also mention it but with the focus of asking for advice or feedback about a particular aspect of it. If there's a new update that's just been released, you can post about that too.

You might just make posts about it from a personal account. You can also consider creating an account specifically for the project.

If you opt for that second option, then when you make a post it will appear to come from the official account rather than the creator of it. This can be more enticing for users to follow, but it really just depends on the situation.

If you're looking for users specifically, see if there's a website dedicated to the kind of thing your project is about.

For example if you make mods for a video game, there's probably a website where you can upload your mod. You can also create your own website to showcase the project. Again it just depends on the situation.

5. Make the most out of Hacktoberfest

Image from Recapping Hacktoberfest

Hacktoberfest is the best opportunity of the year to attract new contributors to your project.

Everyone will be out searching for projects they can contribute to, and a project with a lower barrier to entry is bound to gain some attention.

If you want to make the most of this month-long spike of contributions, make sure you've followed the previous (and following) steps.

This is an especially great time to be a little more active on social media. Share your project on relevant posts, and make your own posts too.

If you come across a list of beginner-friendly projects and yours is indeed friendly, see if you can get yours added to the list.

If you do start getting comments anywhere or contributions (yay!), make sure you're friendly in your interactions.

If you get a contribution from someone but you'd like to request or make a change, that's totally fine. There's nothing wrong with politely letting them know that you have some requested changes.

Remember, this is an event that attracts lots of beginner contributors. We want them to feel welcome! Don't make anyone feel bad for not knowing something or if you need them to modify part of their contribution. Be patient and kind, as you hopefully are even when it isn't Hacktoberfest.

6. Assume good intent until clearly shown otherwise

It might surprise you, but this is an easy one to mess up on.

One of my first contributions got a comment on it saying that the text on a README file was too wordy. I figured that was fine, I can make it more concise. I updated the file.

Someone else commented and said that the file was "quite verbose".

Quite verbose? Are you serious?

That hurt. I was trying to contribute something that I had put a lot of thought into, and I didn't like the phrase "quite verbose". Especially right after I had already made the text shorter.

I was upset, and my response made it apparent to that person. Luckily for me, they responded kindly and we were able to work through it.

It was easy for me to get hung up on that phrase they used. But I should have assumed good intent.

Not everyone uses the same words to describe things. And what they said wasn't clearly intended to be toxic or hurtful. Plus, it was kind of true honestly.

It's tough! You put your heart into something, and then you have to let people critique it. That's how code and other contribution reviews work.

The best advice I have here, is just remember that reviews aren't an attack on your character or how good of a programmer or writer you are. It's simply a review of the contribution itself.

Everyone wants whatever is best. No contribution is absolutely perfect. So try to assume good intent unless it's clearly toxic language or behavior.

7. Ask a friend for feedback

Image by Sasin Tipchai from Pixabay

What's better than getting advice from Internet strangers? Getting advice from a trusted friend, of course!

Whether it's a question about your code, or your social media outreach, or which website layout looks best, don't forget you can always ask a friend for feedback.

If your friends aren't available to help with this kind of thing, you can try to connect with someone on social media.

Making friends on social media can be fun and really helpful. You'll be able to bounce ideas off each other, support each other, and ask each other for feedback.

If you're going to ask for feedback from someone directly on social media, remember to be considerate. If they say no thank you, be polite and don't continue asking them.

If you can't find a specific person who would be good to ask, remember you can always make a public post for anyone to comment on.

8. Show appreciation and share sense of ownership

Image by Gerd Altmann from Pixabay

Always be kind and remember to show appreciation to the people who help you, and to the users of your project.

Give contributors a sense of ownership. People care about the things they own.

I don't mean that you need to literally tell people that they "own" the project. But don't make it feel like they're separated from the project either.

Don't look at it as "this is MY project, MY code, MY community". Think of it as a collaborative effort by everyone. You can just use that kind of phrasing when you speak. "WE did a good job, WE have an awesome community" and so on.

If you look at it as a community thing and not as a "this is all mine" kind of thing, it will show in the language you use. The language you use can make people feel a stronger sense of belonging, or it can make them feel distanced from the project.

9. Build with the user in mind

Image by Gerd Altmann from Pixabay

Remember that at the end of the day, you want your open source project to be useful to other people.

Make sure it's easy enough for users to get started with your project. If you find users asking the same questions, address those frequently asked questions in the instructions or setup process.

Keep in mind what your users would like to see. If they offer you feedback, listen to them and consider the things they say.

Lastly, be sure to always act ethically and have their best interests at heart.

10. Take care of yourself

Image by Free-Photos from Pixabay

Really, truly, take care of yourself.

Contributing to open source can be hard, and maintaining an active open source project is typically even harder.

You'll often find open source projects with tons of open pull requests and Issues.

It can happen if a project is really popular, or if the maintainer becomes overwhelmed and slows down on how many Issues or pull requests they close.

Having a high number of these can get overwhelming really quickly, especially if you don't have much help.

Remember to take a breath. Do what you need to in order to be okay. Your well-being comes before the project.

It's definitely good to consider having a second person who can help actively maintain the project, if things start to get busy.

If you're in school or have a full-time job, it can be especially challenging to manage open source projects on top of it all.

Remember that you're awesome, it's good to take breaks when you feel stressed, and it's okay to ask for help when you need it.

Conclusion

With the right balance and support, maintaining an open source project can be an awesome experience.

I hope that by keeping the above tips in mind, you'll have even more success with your project.

Did I miss anything? Feel free to share your own tips below!

This article was originally published on my personal website's blog, Joy Bytes.

Why contribute to open source and how to get started

Lauren Stephenson — Sat, 01 Aug 2020 21:17:44 +0000

Contributing to open source is a fantastic way to gain valuable experience collaborating with others and working on a "real-world" project.

This is one of my favorite topics to talk about, especially with other students at my university. Open source isn't something you typically learn about in a computer science degree program.

And yet, it can be an incredibly fun and useful way to gain real-world experience with software development.

It is great experience to put on your resume, and can help you land your first internship or even a full-time job. It's useful regardless of whether or not you're a student.

In this article, we'll go over the basics of open source and how to find interesting projects.

We'll also look at a good resource for learning how to actually make a contribution to a project.

If you're already familiar with contributing to open source and you're interested in maintaining your own open source project, feel free to check out that article instead!

So, what is open source?

When software is open source, it means that anybody can look at the code.

Anybody can see how it was made, and they can typically make their own copy of the entire project.

They can use their copy however they want, and change the code if they want. It won't affect the original repository.

Image by Free-Photos from Pixabay

Open source projects are like rooms that you can easily look into and walk inside. You can interact with the things inside the room.

This is different from proprietary software, whose code cannot be viewed openly by the public.

Image by John Collins from Pixabay

You can think of that like the company keeping their code behind a locked door, only available to people who have access to the room.

It's worth noting that neither option is guaranteed to be more secure than the other. Each option comes with its own vulnerabilities.

They are simply two different approaches, each with their own pros and cons.

You can find all kinds of passionate debates about which one is better online. We won't cover that debate in this article, though.

Who uses open source software?

Well, pretty much everyone. There are various places on the Internet that cite different statistics. I won't cite any here, but just know that it is incredibly common both as a user and a company.

Take a look at all of this. Each one of these is either fully open source or involved in open source in some meaningful way.

And that's not even the surface of it. There is a ton of open source software out there. Many, many tools used to develop software are open source too.

It's pretty much everywhere these days.

Why people care about open source

A lot of people are deeply passionate about open source (aka FLOSS; Free Libre Open Source Software). I love this quote, from an article titled "What is Free/Libre, Open Source Software?"

By sharing our improvements and ideas, pooling our resources with thousands, even millions of others around the world via the Internet, the open source community is able to create powerful, stable, reliable software, at very little cost.

That's one of the coolest parts about being in the open source community. And yes, it is very much a true community. It is full of wonderful people, and many tend to care deeply about ethics and freedom.

When people in the community say "free software", they aren't referring to cost. The Free Software Foundation has this to say about it.

Free software developers guarantee everyone equal rights to their programs; any user can study the source code, modify it, and share the program. By contrast, most software carries fine print that denies users these basic rights, leaving them susceptible to the whims of its owners and vulnerable to surveillance.

What you get from contributing to open source

So how does it benefit you specifically? There's a lot of value in it, but here are some of the practical highlights.

Improve as a programmer
Increase confidence
Experience collaborating with others
Community and recognition
Build something, create an impact
Stand out amongst other job applicants
Experience joy and satisfaction
Free t-shirt

Wait wait wait, free t-shirt? Where?!

Hacktoberfest

Image from Recapping Hacktoberfest

That's right, you can get a cool t-shirt if you contribute to open source.

Hacktoberfest is an event that happens every year in October to promote open source and help people learn how to get involved.

Typically, if you sign up on the Hacktoberfest website, you just need to make 4 or 5 open source contributions. Do that, and you can get yourself a snazzy shirt for free! And that's free in terms of cost. ;)

Getting started with GitHub

A great website for getting started with open source software is GitHub. It’s where you and anyone else can upload their coding projects for everyone else to see.

GitHub is a popular place to go for open source projects, and it's what I'll be using for this article. That said, here are some other open source hosting services that you can check out.

When you contribute to someone else’s public GitHub project, you are contributing to open source. If you upload your own project to GitHub and make it public, then your project is open source!

It's highly recommended that projects include licenses to protect the project maintainer and the project itself. This is more important to consider if you want to maintain your own project.

If you're only looking to contribute to a project, then you should be fine if you are acting with good ethics and read their contribution guidelines.

Finding a project

There are over 100 million repositories on GitHub! With 1.6 new repositories created every second, the options are basically limitless. So how do you choose?

Strategy #1: Pick a "practice" project

This is an ideal choice if you have never made a pull request to someone else's GitHub project before.

The idea is to make a contribution to a project that exists solely for getting practice with the overall process.

This is useful because you don't have to worry about what you're actually contributing. It's just so you can get familiar with the process itself.

Check out the First Contributions repo if you want to try this strategy. It's a fantastic repo for learning how to actually make a contribution to a project.

Strategy #2: Collect interesting projects over time

This is an ideal long-term strategy.

The idea is to just keep an eye out for projects that are related to something you are interested in. After all, contributing to something you actually use or appreciate is the most fun.

You can find ideas on GitHub, random blogs, social media, etc.

As you go about your computer/phone activities, pay attention when you come across something you think you'd like to help out as a contributor.

Search online to find out if it is open source or not. If it is, there's a good chance you can find them on GitHub.

If they're on GitHub, you can “star” them as a way of bookmarking them. Over time, you’ll have a unique list of interesting projects you can contribute to!

Feel free to check out my starred projects for some examples.

One beginner-friendly repository I really like is the Awesome First PR Opportunities repo.

It is exactly what it sounds like. You can find lots of great open source projects on there that are beginner-friendly.

Strategy #3: Seek out specific opportunities

There are specific programs and meetups you can find that are all about being involved in open source. The hardest part is just finding them.

If you're a student, check out Google Summer of Code. You can get paid to work on open source over the summer.

Google Summer of Code is a global program focused on bringing more student developers into open source software development. Students work with an open source organization on a 3 month programming project during their break from school.

Many students lost their internships this summer due to COVID-19.

In response to this, Major League Hacking started the MLH Fellowship to help students get experience.

That article came out in May, and stated that they would be paying students to work on open source this summer.

We’re partnering up with GitHub to launch our inaugural 12-week program for Summer 2020. We’ll be funding up to 1,000 students to work full time on major open source projects under the mentorship of experienced engineers.

Of course these opportunities are already under way. Still, various opportunities like these will continue to pop up each year.

Finally, you can also search online for open source or coder meetups.

I live near Kansas City, so I checked on meetup.com and found this Open Source Analytics group.

Looks interesting! This is yet another example of how you might find open source opportunities.

Remember you can also reach out to people you know, whether on social media or in-person. Your friends or coworkers might know about some really great resources.

How to actually make the contribution

So to be honest I wasted like an hour writing a tutorial and taking screenshots for this, only to realize that it wasn't really necessary.

The First Contributions repo has an excellent step by step guide on their README.

Definitely check it out if you want to learn how to actually make a contribution to a project!

Figuring out what to contribute

It can be tempting to jump straight into the code, but hold on a minute before you do that.

Pro Tip: Start with documentation first. You'll learn more about the project and can find easy typos or grammar issues to fix.

This is my favorite way to jump into a new open source project. Even the best documentation writers are prone to accidental typos and grammar mistakes.

Sometimes a section of the documentation is just a bit vague or hard to understand.

As a new contributor to the project, you can provide a fresh pair of eyes to scan the project for easily overlooked problems.

What if the project doesn't have documentation?

Zero documentation makes a project difficult to learn about. You could help just by creating a README for the project.

It doesn't even need to be totally filled out. Just add what information you can, like the project title and a short description describing its purpose, or how to run it on your local machine.

If it's a project that involves visual elements, add a screenshot or GIF showing the project in action.

I did this once for someone's open source project. It was a small improvement, but even adding a simple README can go a long way.

Next steps after documentation

The easiest way to find specific problems to solve is by searching a project’s “Issues” to see what existing problems have been documented.

Keep an eye out for labels like “beginner-friendly”, “good first issue”, “first timers only”, and so on.

You can even search for specific labels across all of GitHub using the main search bar.

For example, to search for all Issues on all public GitHub repositories that use the "good first issue" tag, type is:open is:issue label:"good first issue" into the search bar.

You can also filter the results on any repo by clicking the "Label" dropdown on its GitHub Issues page.

As you work on an existing issue or just try running the project and navigating it as a user, you might find bugs or notice things that could be added or improved upon.

You can create a new issue on the project to document the problem or new feature idea.

This gives project maintainers a chance to discuss the issue with you and hash out any important details before getting deep into writing the solution.

It's common practice to make sure there is an issue documented on the Issues page before adding the change.

If no one has added the issue yet, you can add it to the Issues page yourself.

Still, every project has their own way of doing things. Make sure you read their contributing guidelines before you try to get your changes added to the project.

Getting an employer to notice

Put your GitHub account link on your resume. Share it on Linkedin, Twitter, or whatever other relevant social media you use.

If you have a portfolio or personal website, use that instead.

Consider adding a section for open source projects on your resume, or including it under any relevant list of projects/experiences.

GitHub is not a replacement for a portfolio, but it is definitely good to show employers if you don’t have a portfolio built out already.

Recruiters probably won’t spend much, if any, time looking at the projects. Hiring managers (and/or hiring teams) probably will.

Keep in mind, it is totally fine that your code isn’t perfect. Hiring managers aren’t looking for perfection.

Image by Sue Styles from Pixabay

Be prepared to talk about your projects and/or open source contributions during your interview.

They just want to see things you’ve worked on. It makes for a good talking point that either party can bring up during the interview.

Make sure the link to your GitHub goes straight to your profile page.

You can add up to 6 projects to your profile page as featured repositories. Add the ones you want them to see.

Don't want anyone looking at your code? Totally normal to feel that way. But most developers are never completely satisfied with their code.

Something to show is usually better than nothing.

How open source helped me get a job

I landed my first coding job, in part, to my GitHub profile. At the time I had maybe 6 or 7 projects, and I thought just about every one of them were awful.

I had never contributed to open source at this point, but my personal projects were all open source. Anyone could look at my code.

I had one project I felt was decent enough. I pinned it to my profile, and linked my GitHub profile on my resume.

During the interview, my GitHub profile was brought up.

I don't remember if they brought it up or I did, but the point is that it was brought up. We discussed it, and that discussion contributed to me getting hired.

After I had started the job, I talked to one of the people who had interviewed me. They flat-out told me that they were glad I had linked my GitHub on my resume.

I was the only one who did, and it gave them better insight into what kind of coding experience I had.

And the funny thing is, they said that while they were running it they managed to break it. There were bugs in my code and it was obvious.

Image by Andrew Martin from Pixabay

Seriously, a poorly-coded project played a big role in securing my first tech job.

Even though it was far from perfect, it was better than nothing.

I'm sure that my overall experience level was taken into account. I wasn't far along in college yet. My only other experience was working at my community college and being a crossing guard for a year.

So bare in mind that there will be many factors considered.

If you have 10 years of experience but only a few beginner-level projects, maybe don't link your GitHub.

But if you're looking for an internship, or an entry-level coding position, this kind of thing could be really beneficial even if you think your code isn't very good.

As you get better at coding, you'll have more and more interesting projects to show employers.

The code will never be perfect, but you'll continue to improve over time and it will show in your projects.

Creating your own open source project

Another interesting way to get involved in open source is to start your own open source project!

The basics are pretty straightforward, but there are a few different key features that tend to get overlooked when you're maintaining one for the first time.

There's also the task of getting people to actually use your project. Not to mention finding people who are willing to help contribute to it.

I've made plenty of mistakes along the way with my own open source projects, and I can't wait to share what I've learned with you.

Next week I'll cover how to get started with your own open source project, plus some tips for success.

Conclusion

I hope this article has helped you understand open source better. I also hope you will give contributing a try!

Even if you decide you don't want to do it regularly, it's a good thing to try at least once.

Remember to check back next week if you're interested in starting your own open source project, or learning some tips for success!

Have you ever contributed to open source? Do you have any recommended beginner-friendly projects that new contributors could try? Let us all know in the comments below!

This article was originally published on my personal website's blog, Joy Bytes.

Improve your Git workflow and save time with Git hooks

Lauren Stephenson — Mon, 15 Jun 2020 14:48:49 +0000

If you're a software developer, you probably know about Git. You might use it for version control at work or for side projects. One interesting feature you may not have used yet, at least not intentionally, is a Git hook.

Git hooks are custom scripts that you can use to automate tasks that will be triggered either immediately before or after a Git command is executed.

The Git book explains it best in their Customizing Git - Git Hooks section.

Like many other Version Control Systems, Git has a way to fire off custom scripts when certain important actions occur. There are two groups of these hooks: client-side and server-side. Client-side hooks are triggered by operations such as committing and merging, while server-side hooks run on network operations such as receiving pushed commits. You can use these hooks for all sorts of reasons.

In this article, we will cover two things.

A simple way to add a new Git hook.
How to setup Git hooks for a project in a way that allows everyone to use them automatically. This means no one else will need to manually set anything up for the hooks to work.

Has this ever happened to you?

Do you ever push your code, only to realize you forgot to run that darn formatting command? There's a Git hook for that!

Do you leave little comments in your code to remind yourself of things to fix, only to commit those comments by accident? Don't worry, there's a Git hook for that too!

Ever wonder why your code doesn't work after checking out a new branch, only to realize it's because you forgot to update submodules (again)? Let's "Git" hooked on Git hooks. (Ha!)

Stepping through a simple example

Okay, let's see what it looks like to go through each step of adding a Git hook to a project.

First we need to think of a task that we could automate. Say you like to write "FIXME" as a comment next to whatever needs to be fixed in the code. You plan to fix them before committing. Once you are finished, you remove the comment.

You probably remember to fix most of them, but once in a while you lose track and accidentally commit one or two of the comments or unfinished code sections. How can we prevent this from happening?

We can add a Git hook that will prevent us from successfully commiting code if it detects the phrase "FIXME" in any of the modified files.

First we need to write the hook. The simplest version might look something like this.

View this code snippet on GitHub

What this code is doing

This is our Git hook script. A script can be written in many different languages. This one happens to be written in Bash.

You always use a shebang at the top of the hook script to specify which language you are writing it in. A shebang always starts with #!/.

Our shebang is #!/bin/bash because we are writing our script in Bash. Other common shebangs you might see are:

#!/usr/bin/perl
#!/usr/bin/python3
#!/usr/bin/env bash

We also need to specify the phrase that we want to search for in the code. Whatever phrase you put as the value for the variable "SEARCH_TERM" is what the script will detect and then prevent from being committed.

The last block of code is where we do the legwork of searching for the term and the logic for handling that. If it detects the search term anywhere in the modified files, it will display the messages we've written and then exit with a status of 1.

Exit 1 means that something went wrong, so the script stops and Git will not proceed with the commit.

If the search term is not detected however, then the logic inside our if-statement is ignored and it reaches the end of our script.

At this point it is implied that it exits with a status of 0. Exit 0 means that the script finished successfully, and so Git will proceed with the commit.

Putting our script to work

Now that our hook is written, we just need to place it in the designated hooks folder in our project that uses Git.

The folder we want to navigate to is the .git/hooks folder inside our local repository. The .git folder is hidden by default, but every repository that uses Git has one. Once there, we just need to place our new script inside.

We create a new file here and paste the code snippet inside. When we save it, we will name the file "pre-commit", without any file extension. Doing this will tell Git that this file is a Git hook script, and is specifically a pre-commit hook.

You'll notice there are several types of Git hooks in the .git/hooks folder by default. Each file has an example of something you can do with that type of Git hook. For a full list of the types of Git hooks available, check out the Git hooks documentation.

Great! Now we're ready to see it in action. Let's say we have a file in our project with the comment "FIXME" above a block of code we're working on.

Pretending we haven't noticed that code comment, we stage our file and then commit it. Oops! Luckily, our Git hook is ready to save the day. Let's see what happens.

Our pre-commit hook was triggered automatically, and scanned the file for the phrase "FIXME". It detected the phrase and forced our commit to fail.

Good thing we left a useful error message so we weren't left totally confused. Now we can either finish fixing whatever the code issue was, or if it's done then we just need to remove the comment.

After we remove that comment, we can successfully commit the code.

A couple of things you might be wondering. Does this work if we write "FIXME" in lowercase? What if we write it like "FIXME:" instead? Also, is this hook checking for comments only, or if the phrase found its way into a block of text inside an HTML <p> tag, would it still stop the commit?

The phrase is case-sensitive based on how we wrote our hook, so in this case it needs to be all uppercase. Any characters surrounding it won't matter though, as long as it says exactly "FIXME". Our hook is only checking for that phrase, so it will work even if it is found outside of a code comment.

This is a simple example, but you can create more complex hooks to automate trickier Git workflows too.

You can find a variety of Git hook examples on a GitHub repository that I have linked at the bottom of this article under the Conclusion section.

Adding Git hooks to a team project

Manually adding a Git hook to your project is fine, especially if it's a solo project. But what about your team's project? How can we allow everyone to benefit from your Git hooks?

It's actually pretty straightforward if you use Husky, a tool specifically developed to make sharing Git hooks easy.

Let's say you want to add automatic code formatting to your project, to help keep the code looking consistent. We can use Prettier, a popular formatting tool. Here are the steps you'd take.

Install Prettier with npm i prettier --save-dev
Install Husky and lint-staged with npx mrm lint-staged
Add this as another script under your package.json scripts: "prettier": "prettier --write '**/*.js'"

It's that easy! Once these changes are added to the project, the prettier formatter will automatically run on any modified files that do not match the formatting settings.

Note that the files this example checks are any that match the glob pattern **/*.js which means any JavaScript files in the project.

To specify what types of files you want it to check, change the glob pattern. So if, for example, you wanted it to check both JavaScript and markdown files, you would change the glob pattern to **/*.{js, md}.

You can also execute npm run prettier manually to run it on all current files that match the glob pattern in the project. This is useful if you want to use prettier but already have a lot of existing code that needs the formatting updated.

You can find more information on automating Prettier with Git hooks on the Prettier pre-commit hook documentation.

Conclusion

I wanted a place to keep a list of all the useful Git hooks I've come across or written over time, and that place is my Awesome Git Hooks repository on GitHub. Feel free to check there for Git hook ideas.

Have a useful Git hook to share? Please consider contributing it to the GitHub repo, if it's not already on there. Let's help each other make the most out of Git hooks!

If you don't already use Git hooks in your day to day coding, I hope you'll give it a try. Automating your Git workflow will save you time and can prevent all kinds of mistakes from happening.

Have you used Git hooks before? Which ones do you use the most? Let me know what you think about hooks in the comments below!

This article was originally published on my personal website's blog, Joy Bytes.