├── requirements.txt ├── .gitignore ├── manual-sample-repo ├── img │ ├── header.png │ ├── license_risk.png │ ├── two_license.png │ ├── Multi-licensing.png │ ├── exchange_license.png │ ├── included_license.png │ ├── Multi-licensing-github.png │ ├── license_compatibility.png │ ├── meraki-cli-exchange-devenv.png │ ├── webexteamsbot-exchange-devenv.png │ └── automation-scripts-exchange-devenv.png ├── NOTICE ├── CONTRIBUTING.md ├── LICENSE ├── CODE_OF_CONDUCT.md ├── open-source_license_guide.md └── README.md ├── NOTICE ├── {{cookiecutter.project_name}} ├── NOTICE ├── LICENSE ├── README.md └── .gitignore ├── cookiecutter.json ├── USECASE.md ├── CONTRIBUTING.md ├── LICENSE ├── README.md └── CODE_OF_CONDUCT.md /requirements.txt: -------------------------------------------------------------------------------- 1 | cookiecutter==2.1.1 2 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # OS generated files # 2 | .DS_Store 3 | -------------------------------------------------------------------------------- /manual-sample-repo/img/header.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CiscoDevNet/code-exchange-repo-template/HEAD/manual-sample-repo/img/header.png -------------------------------------------------------------------------------- /manual-sample-repo/img/license_risk.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CiscoDevNet/code-exchange-repo-template/HEAD/manual-sample-repo/img/license_risk.png -------------------------------------------------------------------------------- /manual-sample-repo/img/two_license.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CiscoDevNet/code-exchange-repo-template/HEAD/manual-sample-repo/img/two_license.png -------------------------------------------------------------------------------- /manual-sample-repo/img/Multi-licensing.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CiscoDevNet/code-exchange-repo-template/HEAD/manual-sample-repo/img/Multi-licensing.png -------------------------------------------------------------------------------- /manual-sample-repo/img/exchange_license.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CiscoDevNet/code-exchange-repo-template/HEAD/manual-sample-repo/img/exchange_license.png -------------------------------------------------------------------------------- /manual-sample-repo/img/included_license.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CiscoDevNet/code-exchange-repo-template/HEAD/manual-sample-repo/img/included_license.png -------------------------------------------------------------------------------- /manual-sample-repo/img/Multi-licensing-github.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CiscoDevNet/code-exchange-repo-template/HEAD/manual-sample-repo/img/Multi-licensing-github.png -------------------------------------------------------------------------------- /manual-sample-repo/img/license_compatibility.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CiscoDevNet/code-exchange-repo-template/HEAD/manual-sample-repo/img/license_compatibility.png -------------------------------------------------------------------------------- /manual-sample-repo/img/meraki-cli-exchange-devenv.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CiscoDevNet/code-exchange-repo-template/HEAD/manual-sample-repo/img/meraki-cli-exchange-devenv.png -------------------------------------------------------------------------------- /manual-sample-repo/img/webexteamsbot-exchange-devenv.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CiscoDevNet/code-exchange-repo-template/HEAD/manual-sample-repo/img/webexteamsbot-exchange-devenv.png -------------------------------------------------------------------------------- /manual-sample-repo/img/automation-scripts-exchange-devenv.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CiscoDevNet/code-exchange-repo-template/HEAD/manual-sample-repo/img/automation-scripts-exchange-devenv.png -------------------------------------------------------------------------------- /NOTICE: -------------------------------------------------------------------------------- 1 | code-exchange-repo-template 2 | 3 | Copyright (c) 2023, Cisco Systems, Inc. and/or its affiliates 4 | 5 | This project includes software developed at Cisco Systems, Inc. and/or its affiliates. 6 | -------------------------------------------------------------------------------- /manual-sample-repo/NOTICE: -------------------------------------------------------------------------------- 1 | code-exchange-repo-template 2 | 3 | Copyright (c) 2021, Cisco Systems, Inc. and/or its affiliates 4 | 5 | This project includes software developed at Cisco Systems, Inc. and/or its affiliates. 6 | -------------------------------------------------------------------------------- /{{cookiecutter.project_name}}/NOTICE: -------------------------------------------------------------------------------- 1 | {{ cookiecutter.project_name }} 2 | 3 | Copyright (c) 2021, Cisco Systems, Inc. and/or its affiliates 4 | 5 | This project includes software developed at Cisco Systems, Inc. and/or its affiliates. 6 | -------------------------------------------------------------------------------- /cookiecutter.json: -------------------------------------------------------------------------------- 1 | 2 | { 3 | "project_name": "my-awesome-devnet-code-exchange-project", 4 | "project_description": "baseline DevNet Code Exchange Project", 5 | "author_name": "Your Name Here", 6 | "author_email": "youremail@domain.com" 7 | } -------------------------------------------------------------------------------- /USECASE.md: -------------------------------------------------------------------------------- 1 | {{Use Case Title}} 2 | ===================================== 3 | {{Use Case SubTitle} 4 | 5 | (optional) Describe the use case for Automation Exchange entries here. [DevNet Automation Exchange](https://developer.cisco.com/network-automation/) provides shared code repositories for gathering information from your network, performing audits, activating policy changes, or managing applications, users, or devices. This file serves as a template to collect related links for Automation Exchange submissions. 6 | 7 | Use [GitHub Flavored Markdown](https://github.github.com/gfm/) formatting in this file. 8 | 9 | ## White Paper 10 | Provide links to related white papers: 11 | [CHANGE LINK AND TEXT TO REAL WHITE PAPER](http://www.url_of_your_whitepaper.com/) 12 | 13 | ## Related Sandbox 14 | Provide a link to a related DevNet Sandbox: 15 | [CHANGE EXAMPLE SANDBOX Multi-IOS Cisco Test Network Sandbox](https://devnetsandbox.cisco.com/RM/Diagram/Index/6b023525-4e7f-4755-81ae-05ac500d464a?diagramType=Topology) 16 | 17 | ## Links to DevNet Learning Labs 18 | Provide links to related Learning Labs or modules on DevNet: 19 | [CHANGE EXAMPLE Introduction to Model Driven Programmability(ex: NETCONF/YANG)](https://developer.cisco.com/learning/modules/intro-device-level-interfaces) 20 | 21 | ## Solutions on Ecosystem Exchange 22 | Provide links to related solutions on DevNet Ecosystem Exchange: 23 | [CHANGE EXAMPLE Physical Density Controls](https://developer.cisco.com/ecosystem/meraki/apps/5ed8fa69a0774c0a8cf97e9b/) 24 | 25 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Guidance on how to contribute 2 | 3 | Contributions to this code are welcome and appreciated. 4 | Please adhere to our [Code of Conduct](./CODE_OF_CONDUCT.md) at all times. 5 | 6 | > All contributions to this code will be released under the terms of the [LICENSE](./LICENSE) of this code. By submitting a pull request or filing a bug, issue, or feature request, you are agreeing to comply with this waiver of copyright interest. Details can be found in our [LICENSE](./LICENSE). 7 | 8 | There are two primary ways to contribute: 9 | 10 | 1. Using the issue tracker 11 | 2. Changing the codebase 12 | 13 | 14 | ## Using the issue tracker 15 | 16 | Use the issue tracker to suggest feature requests, report bugs, and ask questions. This is also a great way to connect with the developers of the project as well as others who are interested in this solution. 17 | 18 | Use the issue tracker to find ways to contribute. Find a bug or a feature, mention in the issue that you will take on that effort, then follow the _Changing the codebase_ guidance below. 19 | 20 | 21 | ## Changing the codebase 22 | 23 | Generally speaking, you should fork this repository, make changes in your own fork, and then submit a pull request. All new code should have associated unit tests (if applicable) that validate implemented features and the presence or lack of defects. 24 | 25 | Additionally, the code should follow any stylistic and architectural guidelines prescribed by the project. In the absence of such guidelines, mimic the styles and patterns in the existing codebase. 26 | -------------------------------------------------------------------------------- /manual-sample-repo/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Guidance on how to contribute 2 | 3 | Contributions to this code are welcome and appreciated. 4 | Please adhere to our [Code of Conduct](./CODE_OF_CONDUCT.md) at all times. 5 | 6 | > All contributions to this code will be released under the terms of the [LICENSE](./LICENSE) of this code. By submitting a pull request or filing a bug, issue, or feature request, you are agreeing to comply with this waiver of copyright interest. Details can be found in our [LICENSE](./LICENSE). 7 | 8 | There are two primary ways to contribute: 9 | 10 | 1. Using the issue tracker 11 | 2. Changing the codebase 12 | 13 | 14 | ## Using the issue tracker 15 | 16 | Use the issue tracker to suggest feature requests, report bugs, and ask questions. This is also a great way to connect with the developers of the project as well as others who are interested in this solution. 17 | 18 | Use the issue tracker to find ways to contribute. Find a bug or a feature, mention in the issue that you will take on that effort, then follow the _Changing the codebase_ guidance below. 19 | 20 | 21 | ## Changing the codebase 22 | 23 | Generally speaking, you should fork this repository, make changes in your own fork, and then submit a pull request. All new code should have associated unit tests (if applicable) that validate implemented features and the presence or lack of defects. 24 | 25 | Additionally, the code should follow any stylistic and architectural guidelines prescribed by the project. In the absence of such guidelines, mimic the styles and patterns in the existing codebase. 26 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | BSD 3-Clause License 2 | 3 | Copyright (c) 2023, Cisco Systems, Inc. and/or its affiliates 4 | 5 | Redistribution and use in source and binary forms, with or without 6 | modification, are permitted provided that the following conditions are met: 7 | 8 | * Redistributions of source code must retain the above copyright notice, this 9 | list of conditions and the following disclaimer. 10 | 11 | * Redistributions in binary form must reproduce the above copyright notice, 12 | this list of conditions and the following disclaimer in the documentation 13 | and/or other materials provided with the distribution. 14 | 15 | * Neither the name of the copyright holder nor the names of its 16 | contributors may be used to endorse or promote products derived from 17 | this software without specific prior written permission. 18 | 19 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 20 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 22 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 23 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 25 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 26 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 27 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 | -------------------------------------------------------------------------------- /manual-sample-repo/LICENSE: -------------------------------------------------------------------------------- 1 | # BSD 3-Clause License 2 | 3 | Copyright (c) 2023, Cisco Systems, Inc. and/or its affiliates 4 | 5 | Redistribution and use in source and binary forms, with or without 6 | modification, are permitted provided that the following conditions are met: 7 | 8 | * Redistributions of source code must retain the above copyright notice, this 9 | list of conditions and the following disclaimer. 10 | 11 | * Redistributions in binary form must reproduce the above copyright notice, 12 | this list of conditions and the following disclaimer in the documentation 13 | and/or other materials provided with the distribution. 14 | 15 | * Neither the name of the copyright holder nor the names of its 16 | contributors may be used to endorse or promote products derived from 17 | this software without specific prior written permission. 18 | 19 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 20 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 22 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 23 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 25 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 26 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 27 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 | -------------------------------------------------------------------------------- /{{cookiecutter.project_name}}/LICENSE: -------------------------------------------------------------------------------- 1 | BSD 3-Clause License 2 | 3 | Copyright (c) 2023, Cisco Systems, Inc. and/or its affiliates 4 | 5 | Redistribution and use in source and binary forms, with or without 6 | modification, are permitted provided that the following conditions are met: 7 | 8 | * Redistributions of source code must retain the above copyright notice, this 9 | list of conditions and the following disclaimer. 10 | 11 | * Redistributions in binary form must reproduce the above copyright notice, 12 | this list of conditions and the following disclaimer in the documentation 13 | and/or other materials provided with the distribution. 14 | 15 | * Neither the name of the copyright holder nor the names of its 16 | contributors may be used to endorse or promote products derived from 17 | this software without specific prior written permission. 18 | 19 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 20 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 22 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 23 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 25 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 26 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 27 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 | -------------------------------------------------------------------------------- /{{cookiecutter.project_name}}/README.md: -------------------------------------------------------------------------------- 1 | # {{ cookiecutter.project_name }} 2 | 3 | {{ cookiecutter.project_description }} 4 | 5 | ![add-image-here]() 6 | 7 | ## Use Case Description 8 | 9 | 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. 10 | 11 | ## Installation 12 | 13 | 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. 14 | 15 | ## Configuration 16 | 17 | If the code is configurable, describe it in detail, either here or in other documentation that you reference. 18 | 19 | ## Usage 20 | 21 | Show users how to use the code. Be specific. 22 | Use appropriate formatting when showing code snippets or command line output. 23 | 24 | ### DevNet Sandbox 25 | 26 | A great way to make your repo easy for others to use is to provide a link to a [DevNet Sandbox](https://developer.cisco.com/site/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. 27 | 28 | ## How to test the software 29 | 30 | Provide details on steps to test, versions of components/dependencies against which code was tested, date the code was last tested, etc. 31 | If the repo includes automated tests, detail how to run those tests. 32 | If the repo is instrumented with a continuous testing framework, that is even better. 33 | 34 | 35 | ## Known issues 36 | 37 | Document any significant shortcomings with the code. If using [GitHub Issues](https://help.github.com/en/articles/about-issues) to track issues, make that known and provide any templates or conventions to be followed when opening a new issue. 38 | 39 | ## Getting help 40 | 41 | Instruct users how to get help with this code; this might include links to an issues list, wiki, mailing list, etc. 42 | 43 | **Example** 44 | 45 | If you have questions, concerns, bug reports, etc., please create an issue against this repository. 46 | 47 | ## Getting involved 48 | 49 | 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. 50 | 51 | General instructions on _how_ to contribute should be stated with a link to [CONTRIBUTING](./CONTRIBUTING.md) file. 52 | 53 | ## Author(s) 54 | 55 | This project was written and is maintained by the following individuals: 56 | 57 | * {{ cookiecutter.author_name }} <{{ cookiecutter.author_email }}> 58 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Code Exchange Repo Template 2 | 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](https://developer.cisco.com/codeexchange/). 3 | 4 | ## Instructions 5 | 6 | You have two options, if you have familiarity with Python, use the cookiecutter steps. Otherwise you can manually create a copy of this repo template. 7 | 8 | 9 | ### Cookiecutter Automated Repo Creation 10 | 11 | This process uses [cookiecutter](https://github.com/audreyr/cookiecutter) to auto-generate the files for you. This is helpful if you create multiple use cases. 12 | 13 | > Note: This template assumes the BSD 3-Clause License, you can change it be other licenses afterwards if that is not what you want. 14 | 15 | 16 | 1. Issue this command `pip install cookiecutter` to get ready to use the template. 17 | 2. Use this command and answer the questions: `cookiecutter https://github.com/CiscoDevNet/code-exchange-repo-template` 18 | 3. Update the [README](./README.md), replacing the contents below as described in text within each section of the README. Feel free to combine or omit sections where appropriate. 19 | 4. Update the [LICENSE](./LICENSE), replacing the file with the license selected for your code. See the [*Licensing info*](https://github.com/CiscoDevNet/code-exchange-repo-template/tree/main/manual-sample-repo#licensing-info) section of this README for more info. 20 | 5. Delete these instructions and everything up to the _Project Title_ from the README. 21 | 6. Write some great software and [submit](https://developer.cisco.com/codeexchange/github/submit) it to Code Exchange and/or Automation Exchange. 22 | 23 | 24 | 25 | #### Example 26 | ```bash 27 | use-cases$ cookiecutter https://github.com/CiscoDevNet/code-exchange-repo-template 28 | project_name [my-awesome-devnet-code-exchange-project]: my-first-project 29 | project_description [baseline DevNet Code Exchange Project]: New Things to come! 30 | author_name [Your Name Here]: User Name 31 | author_email [youremail@domain.com]: user@cisco.com 32 | use-cases$ tree 33 | devnet-code-exchange/ my-first-project/ 34 | cookiecutter-devnet-code-exchange/ 35 | use-cases$ tree my-first-project/ 36 | my-first-project/ 37 | ├── LICENSE 38 | ├── NOTICE 39 | └── README.md 40 | 41 | 0 directories, 3 files 42 | use-cases$ 43 | ``` 44 | 45 | ### Manual Repo Creation 46 | 47 | If you are only creating one use case, this process is probably easier. 48 | 49 | 1. Create a new repository. 50 | 2. Copy all the files inside `manual-sample-repo` into your new repository. 51 | 3. Update the [README](./README.md), replacing the contents below as described in text within each section of the README. Feel free to combine or omit sections where appropriate. 52 | 4. Update the [LICENSE](./LICENSE), replacing the file with the license selected for your code. See the [*Licensing info*](https://github.com/CiscoDevNet/code-exchange-repo-template/tree/main/manual-sample-repo#licensing-info) section of this README for more info. 53 | 5. Delete these instructions and everything up to the _Project Title_ from the README. 54 | 6. Write some great software and [submit](https://developer.cisco.com/codeexchange/github/submit) it to Code Exchange and/or Automation Exchange. 55 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, sex characteristics, gender identity and expression, 9 | level of experience, education, socio-economic status, nationality, personal 10 | appearance, race, religion, or sexual identity and orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at devnet-github-owners@cisco.com. All 59 | complaints will be reviewed and investigated and will result in a response that 60 | is deemed necessary and appropriate to the circumstances. The project team is 61 | obligated to maintain confidentiality with regard to the reporter of an incident. 62 | Further details of specific enforcement policies may be posted separately. 63 | 64 | Project maintainers who do not follow or enforce the Code of Conduct in good 65 | faith may face temporary or permanent repercussions as determined by other 66 | members of the project's leadership. 67 | 68 | ## Attribution 69 | 70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 71 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 72 | 73 | [homepage]: https://www.contributor-covenant.org 74 | 75 | For answers to common questions about this code of conduct, see 76 | https://www.contributor-covenant.org/faq 77 | -------------------------------------------------------------------------------- /manual-sample-repo/CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, sex characteristics, gender identity and expression, 9 | level of experience, education, socio-economic status, nationality, personal 10 | appearance, race, religion, or sexual identity and orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at devnet-github-owners@cisco.com. All 59 | complaints will be reviewed and investigated and will result in a response that 60 | is deemed necessary and appropriate to the circumstances. The project team is 61 | obligated to maintain confidentiality with regard to the reporter of an incident. 62 | Further details of specific enforcement policies may be posted separately. 63 | 64 | Project maintainers who do not follow or enforce the Code of Conduct in good 65 | faith may face temporary or permanent repercussions as determined by other 66 | members of the project's leadership. 67 | 68 | ## Attribution 69 | 70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 71 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 72 | 73 | [homepage]: https://www.contributor-covenant.org 74 | 75 | For answers to common questions about this code of conduct, see 76 | https://www.contributor-covenant.org/faq 77 | -------------------------------------------------------------------------------- /{{cookiecutter.project_name}}/.gitignore: -------------------------------------------------------------------------------- 1 | # Ansible # 2 | *.retry 3 | 4 | #confd 5 | *.fxs 6 | confd-cdb/* 7 | cli-history/* 8 | *.log* 9 | ssh-keydir/* 10 | *.access 11 | *.data 12 | *_ns.py 13 | 14 | # Compiled source # 15 | *.com 16 | *.class 17 | *.dll 18 | *.exe 19 | *.o 20 | *.so 21 | *.pyc 22 | build/ 23 | dist/ 24 | doc/build/ 25 | 26 | # Packages # 27 | # it's better to unpack these files and commit the raw source 28 | # git has its own built in compression methods 29 | *.7z 30 | *.dmg 31 | *.gz 32 | *.iso 33 | *.jar 34 | *.rar 35 | *.tar 36 | *.zip 37 | 38 | # Logs and databases # 39 | *.log 40 | *.sql 41 | *.sqlite 42 | logs/* 43 | 44 | # OS generated files # 45 | .DS_Store 46 | .DS_Store? 47 | ._* 48 | .Spotlight-V100 49 | .Trashes 50 | .idea 51 | .tox 52 | *.sublime* 53 | *.egg-info 54 | Icon? 55 | ehthumbs.db 56 | Thumbs.db 57 | .eggs 58 | 59 | # User driven backup files # 60 | *.bak 61 | *.swp 62 | 63 | # Generated by pbr while building docs 64 | AUTHORS 65 | ChangeLog 66 | 67 | # Files created by releasenotes build 68 | releasenotes/build 69 | 70 | # Test temp files 71 | tests/common 72 | tests/*.retry 73 | 74 | # Vagrant artifacts 75 | .vagrant 76 | 77 | # Git clones 78 | openstack-ansible-ops 79 | previous 80 | 81 | 82 | # Byte-compiled / optimized / DLL files 83 | __pycache__/ 84 | *.py[cod] 85 | *$py.class 86 | 87 | # C extensions 88 | *.so 89 | 90 | # Distribution / packaging 91 | .Python 92 | build/ 93 | develop-eggs/ 94 | dist/ 95 | downloads/ 96 | eggs/ 97 | .eggs/ 98 | lib/ 99 | lib64/ 100 | parts/ 101 | sdist/ 102 | var/ 103 | wheels/ 104 | *.egg-info/ 105 | .installed.cfg 106 | *.egg 107 | MANIFEST 108 | 109 | # PyInstaller 110 | # Usually these files are written by a python script from a template 111 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 112 | *.manifest 113 | *.spec 114 | 115 | # Installer logs 116 | pip-log.txt 117 | pip-delete-this-directory.txt 118 | 119 | # Unit test / coverage reports 120 | htmlcov/ 121 | .tox/ 122 | .coverage 123 | .coverage.* 124 | .cache 125 | nosetests.xml 126 | coverage.xml 127 | *.cover 128 | .hypothesis/ 129 | .pytest_cache/ 130 | 131 | # Translations 132 | *.mo 133 | *.pot 134 | 135 | # Django stuff: 136 | *.log 137 | .static_storage/ 138 | .media/ 139 | local_settings.py 140 | 141 | # Flask stuff: 142 | instance/ 143 | .webassets-cache 144 | 145 | # Scrapy stuff: 146 | .scrapy 147 | 148 | # Sphinx documentation 149 | docs/_build/ 150 | 151 | # PyBuilder 152 | target/ 153 | 154 | # Jupyter Notebook 155 | .ipynb_checkpoints 156 | 157 | #confd 158 | *.fxs 159 | 160 | # pyenv 161 | .python-version 162 | 163 | # celery beat schedule file 164 | celerybeat-schedule 165 | 166 | # SageMath parsed files 167 | *.sage.py 168 | 169 | # Environments 170 | .env 171 | .venv 172 | env/ 173 | venv/ 174 | ENV/ 175 | env.bak/ 176 | venv.bak/ 177 | 178 | # Spyder project settings 179 | .spyderproject 180 | .spyproject 181 | 182 | # Rope project settings 183 | .ropeproject 184 | 185 | # mkdocs documentation 186 | /site 187 | 188 | # mypy 189 | .mypy_cache/ 190 | 191 | # PYCHARM 192 | 193 | # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and WebStorm 194 | # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839 195 | 196 | # User-specific stuff 197 | .idea/**/workspace.xml 198 | .idea/**/tasks.xml 199 | .idea/**/usage.statistics.xml 200 | .idea/**/dictionaries 201 | .idea/**/shelf 202 | 203 | # Generated files 204 | .idea/**/contentModel.xml 205 | 206 | # Sensitive or high-churn files 207 | .idea/**/dataSources/ 208 | .idea/**/dataSources.ids 209 | .idea/**/dataSources.local.xml 210 | .idea/**/sqlDataSources.xml 211 | .idea/**/dynamic.xml 212 | .idea/**/uiDesigner.xml 213 | .idea/**/dbnavigator.xml 214 | 215 | # Gradle 216 | .idea/**/gradle.xml 217 | .idea/**/libraries 218 | 219 | # Gradle and Maven with auto-import 220 | # When using Gradle or Maven with auto-import, you should exclude module files, 221 | # since they will be recreated, and may cause churn. Uncomment if using 222 | # auto-import. 223 | # .idea/modules.xml 224 | # .idea/*.iml 225 | # .idea/modules 226 | 227 | # CMake 228 | cmake-build-*/ 229 | 230 | # Mongo Explorer plugin 231 | .idea/**/mongoSettings.xml 232 | 233 | # File-based project format 234 | *.iws 235 | 236 | # IntelliJ 237 | out/ 238 | 239 | # mpeltonen/sbt-idea plugin 240 | .idea_modules/ 241 | 242 | # JIRA plugin 243 | atlassian-ide-plugin.xml 244 | 245 | # Cursive Clojure plugin 246 | .idea/replstate.xml 247 | 248 | # Crashlytics plugin (for Android Studio and IntelliJ) 249 | com_crashlytics_export_strings.xml 250 | crashlytics.properties 251 | crashlytics-build.properties 252 | fabric.properties 253 | 254 | # Editor-based Rest Client 255 | .idea/httpRequests 256 | -------------------------------------------------------------------------------- /manual-sample-repo/open-source_license_guide.md: -------------------------------------------------------------------------------- 1 | # Open-source license guide for the Code Exchange platform 2 | 3 | An open-source license is an essential part of the project. The license should keep information about included projects and newly created source files. 4 | 5 | A license for open-source projects is a legal contract that regulates the relationship between the author or authors and the user. The license describes the terms of use of the project or code, including in commercial programs. In addition, the license defines what others can and cannot do with the software components, obligations, and features of use. 6 | 7 | If you want to create or submit a use case for the Code Exchange platform, the following information helps you choose a related license and manage open-source license issues. 8 | 9 | This document helps you understand the following use cases. Choose the one that is appropriate for your project: 10 | 11 | - [Create your project from scratch.](#create-your-project-from-scratch) 12 | - [Friendly licenses for proprietary software.](#friendly-licenses-for-proprietary-software) 13 | - [Multi-licensing, or applying more than one license to the project.](#multi-licensing) 14 | - [The project includes a fork or part of another project with different licenses. Compatibility of licenses.](#forked-projects) 15 | - [Projects without a license](#projects-without-a-license) 16 | 17 | ## Create your project from scratch 18 | 19 | If you have a new simple project or use case where you are confident that partners and customers can use it, choose one of the following licenses: 20 | 21 | ### MIT License 22 | 23 | This license is straightforward. It does not require additional NOTICE files, and you can use the copyright of any organization and trademark. 24 | 25 | **Projects using MIT**: Visual Studio Code, Julia Language, Electron, Angular.js, Rails 26 | 27 | ### Apache 2.0 28 | 29 | If your project involves other contributors and you want to settle patent issues, use Apache 2.0. 30 | 31 | Compared to other permissive licenses, this license includes a patent clause ("3. Grant of Patent License"). The clause governs the disposal of patents, which means that participants grant permission to use any of their patents that may relate to their contribution. 32 | 33 | Also, if you have modified parts of the files or code, you can apply for a new license. Please make sure to indicate all files that have been changed. 34 | 35 | **Projects using Apache 2.0**: Kubernetes, Selenium, TensorFlow 36 | 37 | ### The 3-Clause BSD License 38 | 39 | The modified 3-Clause BSD version includes a non-maintenance clause. This clause protects you or the contributor from using your name in the project if you don't want it. 40 | 41 | **Projects using BSD**: Flutter, libssh2 42 | 43 | ### GNU Lesser General Public License (LGPL) 44 | 45 | GNU LGPL is an ideal choice for libraries and packages. Until 1999, the license was called the GNU Library General Public License. 46 | 47 | The license was created not to violate the principles of free software so that developers can use this license for their libraries and scripts. Other developers and companies can use the relevant projects with the LGPL license without affecting the license of the general or compiled projects, including commercial ones. 48 | 49 | The following diagram shows statistics for the licenses used on the Cisco Exchange platforms. The data includes published use cases as of August 2022. 50 | 51 | ![Exchange License](img/exchange_license.png) 52 | 53 | ## Friendly licenses for proprietary software 54 | 55 | Which license should you choose for a straightforward project as part of proprietary software? There are two types of licenses: 56 | 57 | - **Copyleft** (GNU, Microsoft Public License), 58 | - **Permissive** (Apache, MIT, BSD) 59 | 60 | Copyleft can also be divided into "weak" and "strong." "Strong" includes GNU, and the "weak" includes Eclipse and the GNU LGPL. For weak Copyleft licenses, it is permissible to compile different binary files and release the result with another type of license or not to change the license of the source project. 61 | 62 | Permissive licenses are also known as "commercially friendly." 63 | 64 | The following diagram shows a list of licenses with a level of risk relative to use in proprietary software. The greater the risk, the greater the problem of using correctly licensed components in your proprietary (or paid) software. 65 | 66 | ![License risk](img/license_risk.png) 67 | 68 | ## Multi-licensing 69 | 70 | Some projects are released and published under two or more licenses. Often, multi-licensing in a project involves using both copyleft and proprietary licenses. This principle gives users and organizations more freedom in using the project or code. 71 | 72 | Supporters of the free distribution of code and programs can, for example, leave the GPL license. Proprietary licenses can be used by developers who want to monetize their products or use the project in commercial solutions with patenting and without publishing the code. In addition, several licenses allow you and users to use one of the corresponding licenses. This avoids conflict of licenses when integrating the project into the main application or project in which solutions with other licenses were already involved. 73 | 74 | An example of multi-licensing is the Perl programming language. Perl has a [GPL](https://github.com/Perl/perl5/blob/blead/Copying) license in the Copying file and the [Artistic](https://github.com/Perl/perl5/blob/blead/Artistic) license in the root directory. The README states that it is possible to distribute and modify the project according to the terms of one of the licenses. In addition, the License file may not contain the text of the license directly but information about the licenses under which the project is published or the projects/libraries included in it. 75 | 76 | ![Two-license example](img/two_license.png) 77 | 78 | ### Multi-licensing in GitHub 79 | 80 | ![Multi-licensing in GitHub](img/Multi-licensing-github.png) 81 | 82 | For multi-licensing in GitHub, you must name your license file with the keyword `License`; for example, `License.BSD`, `License_MIT`, and so on. You can add related license text inside this file and place the license file or files in the root directory of your project. 83 | 84 | Submitters and open-source project contributors can also add different licenses to the project, such as the [Cisco Sample Code license](https://developer.cisco.com/site/license/cisco-sample-code-license/). 85 | 86 | ## Forked projects 87 | 88 | You may have a project that includes a fork or part of another project with different licenses. 89 | 90 | ![Multi-licensed project with forks.](img/Multi-licensing.png) 91 | 92 | When your open-source project contains forks of other projects or uses project code with different licenses and copyrights, create a separate directory where you place the licenses of the projects used in your project. Refer to the following examples: 93 | 94 | - [Kubernetes](https://github.com/kubernetes/kubernetes/tree/master/LICENSES) 95 | - [Elasticsearch client](https://github.com/elastic/elasticsearch/tree/main/client/rest/licenses) 96 | - [CockroachDB](https://github.com/cockroachdb/cockroach/blob/master/LICENSE). 97 | 98 | The following diagram shows an example of organizing information about licenses that are used in different parts of Elasticsearch: 99 | 100 | ![Elasticsearch example](img/included_license.png) 101 | 102 | A recommended practice is to add appropriate license and copyright information to each code file, as shown in the following example: 103 | 104 | ![Header example.](img/header.png) 105 | 106 | ### Compatibility of licenses 107 | 108 | Each application or program usually involves many different libraries and projects, each with its license and set of conditions. So how can you ensure that all your licenses are compatible and compliant? 109 | 110 | The following diagram shows an example of compatible licenses. 111 | 112 | ![License compatibility flow](img/license_compatibility.png) 113 | 114 | If the licenses are compatible, there is an arrow between them. The direction of the arrow indicates the more substantial license. A substantial, strong, inclusive license is a license that essentially includes all the critical terms of another license. 115 | 116 | ## Projects without a license 117 | 118 | If the project is published without a license, the project **cannot** be used. 119 | By default, the software is protected by exclusive copyright, and without a license, use is illegal, even if the project is published. The license grants permission to use, copy, distribute, or modify the software without risk of infringement if the terms are met. 120 | We **cannot** publish projects without a license on our platforms. Most organizations and companies also do not publish their projects without licenses. 121 | -------------------------------------------------------------------------------- /manual-sample-repo/README.md: -------------------------------------------------------------------------------- 1 | # Project Title (required) 2 | 3 | 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. 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. 4 | 5 | Pro tips: 6 | 7 | * 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. 8 | * Code Exchange works best with READMEs formatted in [GitHub's flavor of Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). Support for reStructuredText is a work in progress. 9 | 10 | Other things you might include: 11 | 12 | * 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. 13 | * 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. 14 | * Screenshot: If the code has visual components, place a screenshot after the description; e.g., 15 | 16 | 17 | **Sample:** 18 | 19 | A collection of Python Code Samples for Network Management. Includes samples that leverage on-box libraries, as well as samples that use exposed external APIs (NETCONF/RESTCONF, SNMP, SSH, REST, etc). Some examples make use of available SDKs. 20 | 21 | IMAGE 22 | ![](image_path) 23 | 24 | # Use Case (optional) 25 | 26 | Describe the use case for Exchange entries here when you want to describe an automation use case for gathering information from your network, performing audits, activating policy changes, or managing applications, users, or devices. Summarize the problem statement and solution with outcomes, benefits, and metrics in this section. You can also talk about challenges you had to overcome as part of the solution, and optional ideas you have in mind that could further extend your solution. 27 | 28 | **Sample:** 29 | 30 | NetDevOps delivers consistent version-controlled infrastructure configurations, deployed with parallel and automated provisioning. The best way of understanding the real benefits of NetDevOps is to build your own network configuration and see how it works. With this code, you can create a complete environment that demonstrates the following benefits across the whole network: 31 | 32 | - Track the status of network configurations at any point in time. 33 | - Track proposers and approvers for each specific configuration change. 34 | ... 35 | 36 | 37 | ## Installation (required) 38 | 39 | 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. 40 | 41 | **Sample:** 42 | 43 | Clone the repo 44 | ```bash 45 | git clone https://github.com/CiscoDevNet/cisco-sdwan-python.git 46 | ``` 47 | Go to your project folder 48 | ```bash 49 | cd cisco-sdwan-python 50 | ``` 51 | 52 | Set up a Python venv 53 | First make sure that you have Python 3 installed on your machine. We will then be using venv to create an isolated environment with only the necessary packages. 54 | 55 | Install virtualenv via pip 56 | ```bash 57 | pip install virtualenv 58 | ``` 59 | 60 | Create the venv 61 | ```bash 62 | python3 -m venv venv 63 | ``` 64 | 65 | Activate your venv 66 | ```bash 67 | source venv/bin/activate 68 | ``` 69 | 70 | Install dependencies 71 | ```bash 72 | pip install -r requirements.txt 73 | ``` 74 | 75 | ## Configuration (optional) 76 | 77 | If the code is configurable, describe it in detail, either here or in other documentation that you reference. 78 | 79 | ## Usage (required) 80 | 81 | Show users how to use the code. Be specific. 82 | Use appropriate formatting when showing code snippets or command line output. 83 | 84 | **Sample:** 85 | 86 | Set FLASK_APP 87 | ```bash 88 | export FLASK_APP=script.py 89 | ``` 90 | 91 | And run flask app 92 | ```bash 93 | flask run --host 0.0.0.0 --port 8080 94 | ``` 95 | 96 | Go to the App GUI 97 | 98 | Or for example: 99 | Using in the Docker container 100 | There is a Docker image stored on DockerHub (dmickels/fmcapi) you can use to create Docker containers with. 101 | The syntax is as follows: `docker run -i --name fmcapi --rm --name fmcapi -v 'local directory with scripts':/usr/src/app dmickels/fmcapi:latest` 102 | 103 | 104 | Use [GitHub Flavored Markdown](https://github.github.com/gfm/) formatting in this file. 105 | 106 | ## White Paper (optional) 107 | Provide links to related white papers: 108 | [CHANGE LINK AND TEXT TO REAL WHITE PAPER](http://www.url_of_your_whitepaper.com/) 109 | 110 | ## Related Sandbox (optional) 111 | 112 | A great way to make your repo easy for others to use is to provide a link to a [DevNet Sandbox](https://developer.cisco.com/site/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. 113 | 114 | Provide a link to a related DevNet Sandbox: 115 | [CHANGE EXAMPLE SANDBOX Multi-IOS Cisco Test Network Sandbox](https://devnetsandbox.cisco.com/RM/Diagram/Index/6b023525-4e7f-4755-81ae-05ac500d464a?diagramType=Topology) 116 | 117 | ## Links to DevNet Learning Labs (optional) 118 | Provide links to related Learning Labs or modules on DevNet: 119 | [CHANGE EXAMPLE Introduction to Model Driven Programmability(ex: NETCONF/YANG)](https://developer.cisco.com/learning/modules/intro-device-level-interfaces) 120 | 121 | ## Solutions on Ecosystem Exchange (optional) 122 | Provide links to related solutions on DevNet Ecosystem Exchange: 123 | [CHANGE EXAMPLE Physical Density Controls](https://developer.cisco.com/ecosystem/meraki/apps/5ed8fa69a0774c0a8cf97e9b/) 124 | 125 | ## Additional paragraphs (optional) 126 | 127 | ## Known issues (optional) 128 | 129 | Document any significant shortcomings with the code. If using [GitHub Issues](https://help.github.com/en/articles/about-issues) to track issues, make that known and provide any templates or conventions to be followed when opening a new issue. 130 | 131 | ## Getting help (optional) 132 | 133 | Instruct users how to get help with this code; this might include links to an issues list, wiki, mailing list, etc. 134 | 135 | ## Getting involved (optional) 136 | 137 | 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. 138 | 139 | General instructions on _how_ to contribute should be stated with a link to [CONTRIBUTING](./CONTRIBUTING.md) file. 140 | 141 | ## Credits and references (optional) 142 | 143 | 1. Projects that inspired you 144 | 2. Related projects 145 | 3. Books, papers, talks, or other sources that have meaningful impact or influence on this code 146 | 147 | ---- 148 | 149 | ## Additional information (Not part of the template, delete in your Readme) 150 | 151 | ## Licensing info 152 | 153 | 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](https://developer.cisco.com/codeexchange/) requires a commitment to maintain the code and help the community use and contribute to the code. 154 | 155 | 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. 156 | 157 | > Cisco employees can find licensing options and guidance [here](https://wwwin-github.cisco.com/DevNet/DevNet-Code-Exchange/blob/master/GitHubUsage.md#licensing-guidance). 158 | 159 | 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. 160 | 161 | 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](https://opensource.org/licenses). See [detailed instructions](https://help.github.com/articles/licensing-a-repository/#applying-a-license-to-a-repository-with-an-existing-license). 162 | 163 | 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](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository). 164 | 165 | 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](https://opensource.org/licenses/BSD-3-Clause) has the following copyright notice: 166 | 167 | `Copyright (c) , ` 168 | 169 | See the [LICENSE](./LICENSE) for this template repo as an example. 170 | 171 | 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. 172 | 173 | This code is licensed under the BSD 3-Clause License. See [LICENSE](./LICENSE) for details. 174 | 175 | Some licenses, such as Apache 2.0 and GPL v3, do not include a copyright notice in the [LICENSE](./LICENSE) itself. In such cases, a NOTICE file is a common place to include a copyright notice. For a very simple example, see [NOTICE](./NOTICE). 176 | 177 | 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/main/NOTICE](https://github.com/cisco/ChezScheme/blob/main/NOTICE). 178 | 179 | [More about open-source licenses](https://github.com/CiscoDevNet/code-exchange-repo-template/blob/main/manual-sample-repo/open-source_license_guide.md) 180 | 181 | ---- 182 | 183 | ## Best practices 184 | 185 | **Information below can help you make your repo meet our requirements and be more useful to others.** 186 | 187 | ### Good practices 188 | 189 | 1. Manage sensitive data for scripts. For example, store passwords/API keys and other sensitive data in `env.py` or parse them as arguments. In Python, you can use [ConfigParser](https://docs.python.org/3/library/configparser.html) for applications and programs to encrypt sensitive data in your database. 190 | 2. Include in the Installation section how to run your script for different OS like Windows/macOS/Linux. 191 | 3. Print usage if you run the script or program without any input data (support -h -help flags). 192 | 4. Catch an error and print useful information in the console and interface. 193 | 5. Add error management to handle if users miss some parameters or add them in the wrong format. 194 | 6. Add links for resources where users can test code/app. For example, add links DevNet sandboxes (Always-on or reservable). You can find a list of all available sandboxes here [https://devnetsandbox.cisco.com/RM/Topology](https://devnetsandbox.cisco.com/RM/Topology). 195 | 7. Add links where users can download and how to install additional soft/app/libraries that are needed to run your code. For example, an installer for Python, node, and so on. 196 | 8. Add a NOTICE file with copyright if you use GPLv3 or Apache 2.0 license ([sample NOTICE file](https://github.com/CiscoDevNet/opendaylight-sample-apps/blob/master/NOTICE)). 197 | 9. Dockerize app or part of an app like server/client. 198 | 10. At the top of the `Readme.md` file add a hash symbol and the full use case name to create a useful Readme title. As an example, write `# Devicebanner, updates the banner motd on a network device` instead of just 'devicebanner'. 199 | 11. If your repo is connected with Cisco SecureX orchestration workflow, please check if your workflow or atomic action conforms to their best practices using [this tool](https://ciscosecurity.github.io/sxo-05-security-workflows/analyzer/). 200 | 12. Use [Scorecard](https://github.com/ossf/scorecard) as an easy way to judge whether dependencies in your open source project are safe. 201 | 202 | ### Bad practices 203 | 1. Use low quality screenshots. 204 | 3. Users need to rename some files like `variables_template.py`. 205 | 4. Users need to include credentials in source files. 206 | 5. Don’t describe in which format users need to type or paste in file API endpoint or server IP. For example, sometimes devs write in code api_endpoint = “https://" + IP +"/", such that users need to paste the IP only without a slash at the end or a protocol specification. Please clarify this information in README. 207 | --------------------------------------------------------------------------------