This article is for beginners and for those who have not yet published any projects on GitHub. Experienced developers, could find something interesting too and share their best practices in the comments. In this article you will find five simple pieces of advice to improve your GitHub project. Let's go!
1. Write a good Readme
This is important. The readme file is the start-point of your project for a user. How often do you see a project without readme? What do you think about such projects? Probably, no one will use such projects or even explore the code. Write your readme carefully and make it simple and clear. Everyone should understand purpose of the project and its basic usage.
In my opinion, good readme file includes this chapters:
- A one-sentence project description, which describes the purpose of project.
- How to install project. Here you should give link to NuGet or a comprehensive instruction on how to build your project from source.
- Basic usage. Usually unit-tests with lots of comments.
- FAQ. Write about problems that you already have had while developing this project.
- License and thanks.
Make sure to use lots of emoji!
2. Create a NuGet package
NuGet is an excellent tool for package management in .Net. It will dramatically decrease complexity of working with your project for user. Installation of your project will take only one command:
PM> Install-Package %YOUR_PACKAGE_NAME%
Preferable way to create a package is the NuGet Package Explorer utility. If you want to adjust the parameters I recommend to use the CLI
nuget utility (see description here). Before publishing to NuGet don't forget to fill the
projectDescription from your readme file and to include a link to your project's GitHub page on
Ok, your project is published on NuGet. In the next section let's discuss how to maintain it.
3. Add automatic building to your project
Automatic building and unit-tests will simplify support of your project. A lot of online services can do it for you. My choice is AppVeyor, because it's free for Open Source projects and easy to configure. Just point AppVeyor to your GitHub repository and it should just work out-of-the-box. To get continuous deployment of your project to NuGet - specify path to .nuspec file and the ApiKey (more information here).
4. Add badges
This is optional, but it's so exciting to see all valuable information about your project in the first line.
You can find any badge that you want on the Internet:
- badge with .Net framework version
- badge with number of downloads of NuGet package
In my projects I use badge with a last build status from AppVeyor and badge with the last version of package in NuGet.
5. Contribute to community
Last but not least: contribute to community that gathers around your project. By publishing a project to open source you are get responsible for its maintenance. Respond to community questions, improve the documentation and continue developing your project.
Let's improve the .Net open source community together.