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 and/or Automation 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 submit it to Code Exchange and/or Automation Exchange.
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.,
Describe the problem this code addresses, how your code solves the problem, challenges you had to overcome as part of the solution, and optional ideas you have in mind that could further extend your solution.
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.
A great way to make your repo easy for others to use is to provide a link to a DevNet Sandbox that provides a network or other resources required to use this code. In addition to identifying an appropriate sandbox, be sure to provide instructions and any configuration necessary to run your code with the sandbox.
Provide details on steps to test, versions of components/dependencies against which code was tested, date the code was last tested, etc. If the repo includes automated tests, detail how to run those tests. If the repo is instrumented with a continuous testing framework, that is even better.
Document any significant shortcomings with the code. If using GitHub Issues to track issues, make that known 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 issues list, wiki, mailing list, etc.
Example
If you have questions, concerns, bug reports, etc., please create an issue against this repository.
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 file.
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 or Automation 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 OSI approved open source 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.
Some licenses, such as Apache 2.0 and GPL v3, do not include a copyright notice in the LICENSE itself. In such cases, a NOTICE file is a common place to include a copyright notice. For a very simple example, see NOTICE.
In the event you make use of 3rd party code, it is required by some licenses, and a good practice in all cases, to provide attribution for all such 3rd party code in your NOTICE file. For a great example, see https://github.com/cisco/ChezScheme/blob/master/NOTICE.
- Projects that inspired you
- Related projects
- Books, papers, talks, or other sources that have meaningful impact or influence on this code