Six files to include in your next project

If you have written a software project and you would like to open source it, one of the key considerations is what to include in the projects directory.

Files included here should act as a guide for a potential user or even contributor looking forward to understanding your code.

Below are some suggestions on some standard files you can include.

Readme

If nothing else, make sure that this file is there. This will act as the overall road map to your project.

The file should preferably be in markup, this will enable github to automatically parse and display this file whenever someone lands upon it.

See https://help.github.com/articles/github-flavored-markdown/ for more.

Install

Unless your application is one of the rare birds that work straight out of the box, you probably want to provide instructions on installing and deploying the application.

This may include details such as how to pull in dependencies, where to put the project files etc. You may also include details on how to setup a dev environment if your project supports it.

Authors

Give credit where its due, consider listing everyone who helped forge the project.

Changes

This is especially useful for long living projects. In this document you can log any significant changes between the various versions of your application.

Do not assume everyone will read your commit messages or tag comments.

License

Github will usually suggest licenses for you, select one that makes most sense to your project. If you do not include a license file then your code is legally not available for modification or further reuse by other parties. I assume this was not your intention.

FAQ

Your users will run into issues while deploying, using or contributing to your code. As a preemptive measure you should consider having this file to document the most common issues and their suggested solutions. Dealing with support requests is already hard enough as it is, this simple action can cut this requests by up to half.

Before you ask, no, an issue tracker does not count as an FAQ.

News

For particularly large projects, a news document may be an important feature allowing the public to have higher level knowledge of the happenings in your application

What files do u normally include in your own open source? Tell us about it in the comment section below

Facebooktwittergoogle_plusredditpinterestlinkedinmail