Avatar

As part of Cisco DevNet there are two exchange platforms:

  1. DevNet Code Exchange – is an online, curated set of code repositories related to all Cisco technology areas on public GitHub.
  2. DevNet Automation Exchange platform that provides shared code repositories for network automation and guides teams through their journey with a walk-run-fly methodology.

What benefits will you get by submitting your repo:

  • Verification of compliance with the basic Readme requirements
  • Validate and test your prerequisites, installation, and usage instructions
  • We test all repos using DevNet Sandbox, or using resources and workflow that you provide
  • Usually, we can test your repo on different operation systems
  • We also look at your code and can suggest some improvements (where the qualifications and experience of our reviewers allow it)

The DevNet Code Exchange team always tries to send you useful suggestions based on the analysis of your source code and basic technologies.

Some suggestion for repo submitters:

  • Use Meraki v1 instead of v0. Cisco Meraki asks developers to move to v1, as no new endpoints are added to v0 – only v1 will receive feature updates.
  • Share relevant links and suggest you use the latest version of Webex Meetings REST API
  • Describing how to use related Cisco SDK, that can help in your specific case
  • Send submitter link to actual code sample or function that improves your code

After a complex test and checking your repo we collect all suggestions, logs, screenshots, and send it to the submitter.

You can submit your related open source project for Code Exchange and share for Automation Exchange.

Automation Exchange sample page

 

Automation Exchange Use case page

What should this be used for?

You can use the Code Exchange Repo Template that can help you to navigate through the submission process. Here is a sample repo that contains a description of the necessary Readme paragraphs/chapters and content that should be written there.

First of all, you need to make the code of your open source project clear and safe. Also, it’s good if you have comments in your code. Next, you need to write a Readme file with all needed information and installation instructions. Then choose the related license file (this link can help). Licenses that are most common in projects submitted to our Exchange platforms include:

  • 3-Clause BSD License,
  • CISCO SAMPLE CODE LICENSE,
  • MIT License,
  • Apache License 2.0,
  • GNU GPL-v3.0.

A very common mistake is not to add a separate NOTICE file if you use GNU GPL-v3.0 or Apache License 2.0, as the copyright notice is required for these two types of licenses.

Chapters/Paragraphs that are required for repo Readme:

  • The chapter with the name of your repo (where describe general info about repo and the problem that your project solves)
  • Use Case Description
  • Installation
  • Usage

Optional Chapters/Paragraphs:

  • Prerequisites
  • Known issues
  • Getting help
  • Getting involved
  • Sources
  • DevNet Sandbox (links on related sandbox which users can use to test your project)
  • Licensing info (not to be confused with a license file that is mandatory for Code Exchange and Automation Exchange)
  • Authors
  • Thanks

All submitted repositories have the next part that we check:

  • Readme file
  • Source code
  • License file
  • Other files like document, images, etc

Readme is the main part that users see when trying to use your project. So the developer/repo owner needs to describe in detail how to run code from the repository, and describe the main aspects and technologies used in the repository.

Tips

If you mention some file names in Readme that users need to edit or interact with, please markdown text as a link.

All terminal commands need to be markdown as Code, and written in a separate line, so users can easily copy-paste and run this command.

Video tutorials and images, where you show installation and usage of the project,  are most welcome. However, don’t forget to include a clear step-by-step guide in text.

In some cases, it may be good if you ‘Dockerize’ your repo. This can help solve many issues that are connected with different operating systems and environments, and also can help users deploy the project in a few commands.

What next?

After the submitter implements all suggestions, your repo will be approved and published, and the submitter will receive an email with a public link like this. You can add to your Readme Code Exchange badge. Then you can share this achievement on your social account. You can also use it for career advancement and personal brand building.

Here is an example project page after published on Code Exchange

Code Exchange project page sample

Code Exchange Challenge

The Code Exchange Challenge will run until Nov 14, 2020. Get your code approved to win a T-shirt.

code exchange T shirt

(Note: While Cisco employee submissions may be approved and featured in Code Exchange, they are ineligible to receive a free t-shirt at this time.)

Note that Cisco DevNet is not certifying or maintaining the content of all repositories. If you see an issue or have a question about a project, raise it with the project maintainers. If you see an issue or have a question about Code Exchange itself, please report it by email to askcodeexchange@cisco.com