Skip to content

A starter kit for setting up a new repo, including a checklist of what to include in your README and templates for other recommended files

License

Notifications You must be signed in to change notification settings

Nexmo/repo-standards

Repository files navigation

Vonage Repository Standards

Nexmo is now known as Vonage

These are our internal-facing guidelines, published in the open in case anyone else finds them useful.

This project contains checklists, templates and other resources to include with your open source repository. Whether you're starting a new project or improving an existing one, please include any or all of the elements suggested below as appropriate to your repo.

Which GitHub Org?

Historically, we have had a number of GitHub orgs:

  • vonage Our libraries, code snippet repos and other formally supported projects go here.
  • nexmo Many useful older tools and demos can be found in this org, but since the rebrand we typically don't create new projects in this area.
  • vonage-community The community repo where we put sample apps, blog post examples, and other assorted items (things can be promoted into the main repo at a later date if widely adopted).
  • nexmo-community The older Nexmo-branded community repo
  • opentok This is where our libraries, server SDKs and officially supported repos live. You can filter out "labs" projects using the "opentok-labs" topic.
  • opentok-community The community repo where we put OpenTok related sample apps, blog post examples, and other assorted items (things can be promoted into the main repo at a later date if widely adopted).

If you're not sure where something goes, or you don't have permission to create a repo, talk to us in #ask-devrel on slack.

Get the Basics Right

Naming things is hard, this part is very important! Best practice: name the project after what it does rather than what it is made of. E.g. "joke telephone answering service" rather than "sinatra voice demo".

  • Give your repo a description and some topics - you can set these at the very top of the web interface, before the file listings. The description should cover the purpose and scope of the project. The tags should include vonage as well as the technologies used and the features of the project. For example you could have tags: vonage python redis verify 2fa.

  • Every repo must have a license, this will be Apache 2.0 in most cases. See also: GitHub docs for adding a license to your repo and always choose a standard OSI-approved license.

  • Use the basic README template as a starting point for your repository. Look at the project types section for what else to include for your project.

What Type of Project?

While most of our READMEs should have some common features, different repo types have different requirements. Here is what we expect from the different types of repo.

Library (e.g Node.js lib) Demo/Tool (e.g. Demo for booth/customer use) Supporting code (e.g. for blog post)
Installation instructions Installation instructions Link to what this repo is supporting
Detailed usage docs for all features Usage examples App may set User-Agent
CONTRIBUTING FILE CONTRIBUTING FILE
CODE_OF_CONDUCT FILE CODE_OF_CONDUCT FILE
App must set User-Agent App may set User-Agent
  Docker setup
  One-click deployment setup

More README Resources

You may find these resources useful for structuring your project's README file (edit and add your favourites!)

About

A starter kit for setting up a new repo, including a checklist of what to include in your README and templates for other recommended files

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published