Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Software Packaging Guidelines

Software Packaging Guidelines

License

Without a license, the default copyright laws apply, meaning that you retain all rights to your source code and no one may reproduce, distribute, or create derivative works from your work.

Without an open-source license it can be hard for people using your software to be aware in what terms they may contribute back changes or even fork your project.

Suggestion

You should have a file in the root of your repo with a name like license.md, license.txt. It doesn't matter whether it's uppercase or not.

Visit www.choosealicense.com to get help picking the right one for you project. The most common licenses on GitHub seem to be permissive ones like MIT and the FreeBSD/Simplified which allow downstream developers to use and modify the licensed code without having to share their modifications.

Keep in mind though for licenses which allow project take-overs. Permissive licenses allow others to release software containing your work under a commercial license making money out of it.

Remember that in order to change the license for an existing project where many people own the work, an 100% consensus is required for the license to change.

Where applicable specify your license in your project's package manifest (package.json, gemspec, project.clj, etc).

Release Tags

Tags in your version control matching your release versions.

Greatly improves source discoverability. It can be really beneficial during debugging and is an absolute requirement for auditing reasons. People want to know what is the exact snapshot of the code included in your project's x.y.z version.

Suggestion

No matter which versioning scheme your use, you should create a tag for that version.

Example (using git):

You wish to release version 1.4.2 of your source.
You'll first create an annotated tag by running:

git tag -a 'v1.4.2'

You will then be requested to write a message for the tag.

Info to include in a Git release tag:

  • Link to issue tracker milestone
  • Link related changelog entry
  • Contributors involved in the release (give merit ☺)

If you're hosting your project on GitHub you can easily create a release from a tag and add additional information in markdown there.

Protip: GitHub keeps an rss feed for releases (example), making it easy for dependents to be notified to update.

Then share the created tag to your repository host.

git push origin --tags

Documentation Files

Some files providing information to readers of your code have to be present.

Readme

It's the first file someone has to read in your project. It can have any name like README, README.md, README.txt, readme.rdoc and has to exist in the root of the project's repository.

Suggestion

Below there's a small list of things you might want to include in the Readme:

  • Goal of the project - The stated reason of the project's existence
  • System dependencies required to use it
  • Build instructions
  • Usage examples
  • The versioning scheme it adheres to
  • Instructions to run the test suite

Contributing

Has to exist in the root of the project's repository. It's commonly named CONTRIBUTING.md.

Informs people reading your code on the procedure to follow if they wish to contribute back, and the etiquette to conform to for any communication concerning the project.

GitHub will prompt users about to create an issue to your repo to read your guidelines when such a file is found (read about the GitHub feature here).

Suggestion

Add a CONTRIBUTING.md file at the root of your repo.
Some guidelines out in the wild on which you can base yours are:

Changelog

A Changelog is a file communicating changes users should be aware of for each released version of a project.

Dependents should be able to find concise information for a project's changes without looking at the vcs history, to determine the feasibility to upgrade and the steps required.

Suggestion

Add a CHANGELOG.md file at the root of your repository.

A template to base yours:

# Change Log
All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).

## Unreleased

### Added

* Experimantal support for Uranus expedition

## [0.1.1] - 2048-01-12

### Fixed

* Reprogrammed HAL 9000 not to browse reddit

## [0.1.0] - 2048-01-06

### Added

* Autopilot humming sounds

### Changed

* Windshield wipers move 10% faster

### Fixed

* Windows updates no longer restart the ship's engines (#42)

How not to write a changelog: https://github.com/nodejs/node/blob/v2.5.0/deps/npm/CHANGELOG.md

All versions have to be present in the changelog. Decide on the format of the changelog you'll use and be consistent. Use a neutral tone, and exercise brevity. A long list of helpful tips can be found at keepachangelog.com

Release Signing

This way, your users can verify that the release has been approved by the core maintainers of the project.

Suggestion

Make sure to gpg sign your release tags.

git tag -s -a 'v1.4.2'

Additionally, for GitHub you can create signed releases using this guide. Signed commits are marked as verified on GitHub:

signed_commit

Use the following command to have commits gpg signed by default:

git config --global commit.gpgsign true
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.