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.
- 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. Feel free to combine or omit sections where appropriate.
- 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.
Put a meaningful, short, plain-language description of what this code is trying to accomplish, what is the business driver for implementation, and in general why it matters.
Pro tips:
- Code Exchange displays the first few content lines of your README in the tile it creates for your repo. If you enter a GitHub Description, Code Exchange uses that instead.
- Code Exchange works best with READMEs formatted in GitHub's flavor of Markdown. Support for reStructuredText is a work in progress.
Other things you might 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.,
Detailed instructions on how to install, configure, and get the project running. Call out any dependencies. This should be frequently tested and updated to make sure it works reliably, accounts for updated versions of dependencies, etc.
If the code is configurable, describe it in detail, either here or in other documentation that you reference.
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.
If the code includes automated tests, detail how to run those tests.
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.
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.
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. Include information on how to setup a development environment if different from general installation instructions.
General instructions on how to contribute should be stated with a link to CONTRIBUTING.
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.
Cisco employees can find licensing options and guidance here.
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.
- Projects that inspired you
- Related projects
- Books, papers, talks, or other sources that have meaningful impact or influence on this code