Code Exchange Repo Template
This repository is a template to be used when creating a new repository containing sample code, a sample application, or some other software related to Cisco technologies and to be made available for use by the Cisco DevNet community through Code Exchange.
Instructions
- Create a new repository.
- Copy these files into the new repository.
- Update the README, replacing the contents below as described in text within each section of the README.
- Update the LICENSE, replacing the file with the license selected for your code. See the Licensing info section of this README for more info.
- Delete these instructions and everything up to the Project Title from the README.
- Write some great software and tell people about it.
Project Title
Description: Put a meaningful, short, plain-language description of what this code is trying to accomplish and why it matters.
Other things to include:
- Technology stack: Indicate the technological nature of the code, including primary programming language(s) and whether the code is intended as standalone or as a module in a framework or other ecosystem.
- Status: Alpha, Beta, 1.1, etc. It's OK to write a sentence, too. The goal is to let interested people know where what they can expect from this code.
- Screenshot: If the code has visual components, place a screenshot after the description; e.g.,
Dependencies
Describe any dependencies that must be installed for this code to work. This includes programming languages, databases or other storage mechanisms, build tools, frameworks, and so forth. If specific versions of other software are required, or known not to work, call that out.
Installation
Detailed instructions on how to install, configure, and get the project running. This should be frequently tested to ensure reliability.
Configuration
If the code is configurable, describe it in detail, either here or in other documentation to which you link.
Usage
Show users how to use the code. Be specific. Use appropriate formatting when showing code snippets or command line output. If a particular DevNet Sandbox or Learning Lab can be used in to provide a network or other resources to be used with this code, call that out here.
How to test the software
If the code includes automated tests, detail how to run those tests.
Known issues
Document any known significant shortcomings with the code. If using the Issue Tracker, make that known here and provide any templates or conventions to be followed when opening a new issue.
Getting help
Instruct users how to get help with this code; this might include links to an issue tracker, wiki, mailing list, etc.
Example
If you have questions, concerns, bug reports, etc., please file an issue in this repository's Issue Tracker.
Getting involved
This section should detail why people should get involved and describe key areas you are currently focusing on; e.g., trying to get feedback on features, fixing certain bugs, building important pieces, etc.
General instructions on how to contribute should be stated with a link to CONTRIBUTING.
Licensing info
A license is required for others to be able to use your code. An open source license is more than just a usage license, it is license to contribute and collaborate on code. Open sourcing code and contributing it to Code Exchange requires a commitment to maintain the code and help the community use and contribute to the code.
Choosing a license can be difficult and depend on your goals for your code, other licensed code on which your code depends, your business objectives, etc. This template does not intend to provide legal advise. You should seek legal counsel for that. However, in general, less restrictive licenses make your code easier for others to use.
Once you have determined which license is appropriate, GitHub provides functionality that makes it easy to add a LICENSE file to a GitHub repo, either when creating a new repo or by adding to an existing repo.
When creating a repo through the GitHub UI, you can click on Add a license and select from a set of [common open source licenses] (https://opensource.org/licenses). See detailed instructions.
Once a repo has been created, you can easily add a LICENSE file through the GitHub UI at any time. Simply select Create New File, type LICENSE into the filename box, and you will be given the option to select from a set of common open source licenses. See detailed instructions.
Once you have created the LICENSE file, be sure to update/replace any templated fields with appropriate information, including the Copyright. For example, the 3-Clause BSD license template has the following copyright notice:
Copyright (c) <YEAR>, <COPYRIGHT HOLDER>
See the LICENSE for this template repo as an example.
Once your LICENSE file exists, you can delete this section of the README, or replace the instructions in this section with a statement of which license you selected and a link to your license file, e.g.
This code is licensed under the BSD 3-Clause License. See LICENSE for details.
Credits and references
- Projects that inspired you
- Related projects
- Books, papers, talks, or other sources that have meaningful impact or influence on this code