Hi, welcome. Today, I just want to share my experience using GitHub and how I set it up for the project. This article may be interesting for beginners who need to set up their projects to become more professional and enhance their workflows.
Ok, without further ado, let's get into it.
Add better README
The first one I consider to be set up is to create a fantastic and useful README. The README should contain all information about the project, including background, motivation, process, features, and acknowledgment.
Also, some READMEs can contain the guide, instructions, roadmaps, license, and credits. Of course, if you have just a simple project, what you should include is a description and some acknowledgment, including the stack and features.
I have written an article before about Creeate a better README. If you want more detail, please read the article.
Create License
Now let's move into the license section. If your project is an open-source project, you should have a license to protect your work. Most of the general public can choose MIT or GPL. If you are still confused about what license should pick for your project please refer to https://choosealicense.com/
Creating a license on GitHub has now become easy. I will give you an example of how to create an MIT license in just a few seconds.
First, move into your GitHub project. then start creating a new file named "LICENSE. Now you can see a visible button "Choose a license template" in the header of the file name. You can click and start picking out some templates.
Now you can pick the license using MIT. Then fill in some required information, including the year and full name. You can also see what the differences are between the licenses, like permissions, limitations, and conditions.
Now you have a better license for your project, which can be pretty quick.
Add contributing
Now, let's set up a document to let other contributors know what they should do to contribute to your project. This document is very important to other people if they want to contribute and make changes to your code. I made this document straightforward. Here are some details that can be included in the document:
Getting started
Requirements
Pull Request
Issues and feature requests
Security
Testing
Code of conduct
Here are some references that can help you
https://github.com/PostHog/posthog/blob/master/CONTRIBUTING.md
https://github.com/openwrt/packages/blob/master/CONTRIBUTING.md
Changelog
A changelog is used to log all activity when you release new tags, fix bugs, or add features to your release. You can document your app with the tags, then create a record to let others know what changes you make in each release.
Inside the changelog can contain some information
Tags (Versions)
Update
Bug Fixed
Feature added
Code of conduct
Start coding as soon as possible. A code of conduct helps you and the community specify standards, behaviors, and some rules that can protect all members of the community from unexpected behavior that can drain your work.
This document is pretty important, you may need it as soon as the project is created. If you need some questions and need to know what exactly this feature is, you can this post about the Code of Conduct
To create a code of conduct on GitHub, you can simply create it using a template.
Go add a new file called "CODE_OF_CONDUCT.md"
Start by clicking "Choose a Code of Conduct Template"
Modify and save
Branch protection rule
If you work with multiple branches and collaborate with many contributors, I prefer to use a branch protection rule. This can help you protect your branch by using a rule that can help you reduce some actions and commits that have unexpected results.
In my experience, I will create a default branch as the main and protect it. So we can't force a push to the branch, all we can do is merge that. You can also add some features like
Require checks before the merge
Require pull request before the merge
Lock branch
and event signed commits
To start protecting your branch, go ahead into "Settings", then move into "Branches.". Now you can create one. Here are example
Socials preview
Social previewing can't be important, but this enables you to make your project more confident when sharing it with the community on social media sites like Twitter, Facebook, and others.
Social media doesn't impact your workflow as much, however, in my opinion, adding social media can give you more value and make you look more serious. If you want to add your preview, please head to "General" and then move into the "Social Preview" section.
Issues template
Do you realize that we get bored doing the same things repeatedly? That's why I use a template to create an issue. Templates not only help you save the most time but also give you some boilerplate to create an issue. So the user who wants to report a bug or feature request can have some form to fill out.
I personally at least need two types of issue templates: bug reports and feature requests. You can create as much as you want, for example, a security report or other things.
To create your template, you can easily set it up using GitHub. Just go to Settings > General. In the feature section, you can see a template section. You can create your own.
Now, if you want to create issues, you will be redirected to the template page and guided to use the form.
If you choose bug report, you can see an awesome template you can use to make your life easier.
Pull request template
Pull requests are another one. This feature is the same as the Issues template but works for pull requests. The function is mainly the same, however, pull requests are created under the Markdown file.
To create your pull request template. You can create a new file called pull_request_template.md inside the github folder. For more reference, you can see the documentation in Create PR Template Guide
Sponsorship
If your project looks interesting and has an impact on other people, you can ask for donations from other people to help you maintain the project by using sponsors. You can gain some sponsors by using some platforms including
Ko-fi
Github Sponsors
Open Collective
Patreon
and others
This sponsor works for your personal profile or Github organization. If you prefer to use Github Sponsor, you need to setup your account under https://github.com/sponsors/
How to use this money depends on your needs. You can use the money to buy hosting, domains, paid services, integrations, and even some cash for your hard work.
To setup, you can go into Settings -> General and under Sponsorship
Discussion
You have so many participants, users, and contributors. I will set up the discussion. This will enable communication between the user and the participant. How about issues? Well, you can also use the same feature in an issue to discuss and communicate.
However, I use issues to communicate technical information and fix problems, on the other side, discussions are used to create announcements and polls and collect and discuss ideas.
You can setup and enable discussion under "General" settings.
Now, you can see the discussion tab in the top menu of your project and start creating your discussion with your user.
Projects as project management
Now, move on to how to manage my tasks on GitHub. I love this feature a lot. So when I start creating a blank project with my client, I will prefer to use GitHub projects. Not just about including projects in one platform, projects can help me move faster with my development workflows.
All teams can communicate with each other, including designers, developers, and testers, in one place. I never say that you don't need another project manager. But, in my opinion, projects are far enough away to use with your team.
All features, including tasks (as issues), drafts, goals as milestones, roadmaps, and so on. However, one thing missing from projects is the reminder of tasks. You can also manage your multiple repos in a single project. So if you separate your project into different repositories, you are still able to communicate with each other.
Automatic delete head branch
This feature kind of helps you a lot with multi-branches. How do you manage your branch on GitHub? using the feature approach or the environment approach (dev, staging, and production)? I love the feature approach. If you are working with a team and each team has its job, the feature approach can help you.
You will create a branch for each feature you develop. eg, "signin". Now that the feature is ready, you can start to merge the code. Before we jump, you better do a pull request and then assign a tester or reviewer to review your code. So we can create the best quality code.
If the feature is acceptable, you can merge it into the main branch, which will automatically delete your current branch.
Go ahead and enable it in the general settings.
Code security and analysis
This feature helps you keep your repository code updated and secure. You will grant permission for GitHub to do read-only analysis to check your code. There are several points
Vulnerability reporting
Dependency graph
Dependabot
Code scanning
Secret scanning
I enabled all of these features. The ones I love are code scanning and Dependabot. Code scanning will scan your code automatically if you push it. Dependabot will check every dependency in your repository and create a new pull request to merge if an update is found.
Labels & Milestones
Keep the labels that are needed for your project. then start creating a milestone as a target for your next movement. Labels are very useful when you're working with many issues in your repositories. You can filter and manipulate them using labels.
Keep important labels like bux, fix, enhancement, good first issue, dependencies, and documentation, and add your preferences.
Workflows
Now, let's move into continued development. All we can do is set up actions for our repository. If you don't understanding about action you can read more in documentation
At least you should add this workflows in your actions
Build
Linter
Analysis
Testing
Code scanning
You can also use actions to automatically release your app using tags, deploy it, or publish it to a server or Play Store.
You can explore more features on GitHub, I just want to share my experience while using it. If you have any questions or suggestions, you can send me a message on twitter. If there is a misspelled word, please let me know.
Thanks. Have a nice day, developer.