Participant Development Environment - Inconsistency in Directory Structure

[ciscodevnet]

Participant Development Environment - Inconsistency in Directory Structure

[austinMarcos]

In Friday triage meeting, with input from Chris L. decided that this is an issue that we should resolve now while we are in the process of creating a new pod image.

[armartirosyan]

I believe proposed folder structure is ideal solution to our problem.

~/CiscoDevNet          <-- Root directory
|--venv                <-- Folder containing virtual environments for different tracks
   |--dna
   |--cloud-collab
   |--dci
|--code                <-- Folder containing code samples for different tracks
   |--dna
      |--devnet-express-code-samples 
   |--cloud-collab
   |--dci

If there are no objections, I will go ahead and make changes in the DNA track

[cmlccie]

That structure looks good to me! The only modification or input that I would give would be to not add the devnet-express-code-samples folder/repo underneath the dna folder, but rather make-it the dna folder by cloning the repo to the dna folder name - like so:

git clone https://github.com/CiscoDevNet/devnet-express-code-samples.git dna

This shortens path names, and I feel it is a little cleaner / clearer.

[armartirosyan]

@cmlccie @austinMarcos
Should this change be implemented before DevNetExpress event in Las Vegas or after?
Below items need to be updated

• Instructions in all labs
• Screenshots
• Slide decks

[cmlccie]

The DNA track isn't being offered at CLUS (just CC and DCI); however, it would be good to get this new 'standard' over to the other track creators to use in those tracks. It would be good to start off these tracks with the standardized folder structure - if possible.

[hpreston]

This makes sense to me and I agree it's a confusing issue. Having a standard will be great. We will implement in the DCI track that is in development now.

[cmlccie]

Just to confirm, we are looking at the following:

Last login: Sat May 20 12:04:49 on ttys001
~ $ mkdir -p ~/CiscoDevNet/venv

~ $ mkdir -p ~/CiscoDevNet/code

~ $ cd ~/CiscoDevNet
CiscoDevNet $ virtualenv -p python3 venv/dna
<-- Output Omitted -->

CiscoDevNet $ git clone https://github.com/CiscoDevNet/devnet-express-code-samples.git code/dna
<-- Output Omitted -->

CiscoDevNet $ tree -d -L 3
.
├── code
│   └── dna
│       ├── LM-1201
│       ├── LM-4201
│       ├── LM-4302
│       ├── LM-4402
│       ├── LM-4502
│       ├── LM-4602
│       ├── LM-4702
│       ├── LM-4802
│       ├── LM-4901
│       └── NWPLab
└── venv
    └── dna
        ├── bin
        ├── include
        └── lib

17 directories

Which produces nice, intuitive and relatively short relative paths like:
~/CiscoDevNet/code/dna/LM-4201/

Correct?

[hpreston]

@cmlccie one thing I've asked for the code samples on DCI is that after the "LM-XXXX" we include a short description of what the module is. Numbers are great to verify, but can be a pain if you don't intuitively know them. So what I've asked for would be something like this..

LM-5501 intro-aci
LM-5551 intermediate-aci 

Any problems with that small deviation?

[cmlccie]

@hpreston , I completely understand... When looking at the LM-xxxx folders, you don't really know which one is which (was also an issue with the Modulexx naming / numbering scheme).

My input on the names you describe would be to:

1. Keep the names as short as possible (so we don't get the crazy long path names that we have seen with the DNA track).
2. Don't have spaces in the folder name; otherwise, people have issues working with with them - escaping the spaces or having to include quotes (sure you can just hit tab in most Unix/Linux shells, but not everyone knows this and it can cause some minor struggles for people who are just getting started).

So, something like:

LM-5501-intro-aci
LM-5551-intermediate-aci

Is probably ok. However, whatever we do, it would be good to standardize (and we just did change the folder names in the DNA track). 😬

Note that WWSE just contributed some funds to DevNet to help source an additional contracted Tech Writer. Maybe they can help us with all of these documentation revisions. 😎

[hpreston]

@cmlccie good points... we'll work them into the updates.

[austinMarcos]

+1 on Armen's proposed structure:

~/CiscoDevNet          <-- Root directory
|--venv                <-- Folder containing virtual environments for different tracks
   |--dna
   |--cloud-collab
   |--dci
|--code                <-- Folder containing code samples for different tracks

+1 on adding short descriptions to code samples folder names for the Data Center track.

+1 on 'Don't use spaces in the folder names'

@cmlccie I agree that although we are not presenting a DNE for DNA at CLUS 8-) , the week leading up to CLUS would be a good time to update the DNA pod's directory structure (and labs and slides). One advantage is that there are no DNExpress events happening during that week of June 19-23. I'll coordinate with @armartirosyan and @ecorban , who were already looking at updating the DNA pod (/issues/41). If not that week, then the week of July 3.

[austinMarcos]

Based on conversation in DCI scrum today re path for virtual environment folder

~/CiscoDevNet          <-- Root directory
|--venv                <-- Folder containing virtual environments for different tracks
   |--dna
   |--cloud-collab
   |--dci-py2
   |--dci-py3
|--code                <-- Folder containing code samples for different tracks
   |--dna    <--image on pod prepped with this as root of samples
   |--cloud-collab
   |--dci

[cmlccie]

Following past and recent observations from DNE events, we need to have a meeting to discuss at a higher level the end-to-end participant workflow. Tools used, recommended folder structures, and instructions provided all contribute to the participants journey and experience with engaging with these labs and learning track.

I have tagged the open issues related to the participants Development Environment, and I will schedule a call to discuss.

[austinMarcos]

The folder structure in the code samples directory was modified, but the following lab needs to have the instructions and screenshots (of the command line) changed:

https://learninglabs.cisco.com/tracks/devnet-express-dna/devnet-express-np-rest-apic/05-apic-04-mission/step/1

Also, verify that the changes appear in the DCI track:

https://learninglabs.cisco.com/tracks/devnet-express-dci/devnet-express-np-rest-python/04-rest-05-mission/step/1

[armartirosyan]

I removed all inconsistent folder structures and replaced with agreed format. The changes have been pushed to issue19 branch and have been published to stage LLs https://learninglabs.cisco.com:8867/tracks/devnet-express-dna.

If approved, I will issue pull request and will merge it with master branch.

Thanks

[annegentle]

@austinMarcos Can this issue be closed?

[cmlccie]

I do believe they implemented the changes... Though the directory structure is less than optimal. Participants have to move in and out of their code folder (or use relative or absolute path references) to work with their virtual environments. As part of the primer and track re-working, I would recommend the following structure. From seeing the use at the events (and general Python best practices), the best structure for the participants is to co-locate the virtual environment directory within the project root.

This would simplify the setup instructions and subsequent UX in working in the track.

At a macro-level the folder structure could look like so:

~/CiscoDevNet                <-- Root directory
|--tracks                    <-- Folder containing project/repository roots
   |--cc                     <-- Friendly folder name for the cloned repository
      |--.gitignore          <-- Update .gitignore to exclude the venv folder from inclusion in the repo
      |--requirements.txt    <-- PIP requirements file to manage track dependencies
      |--venv                <-- The virutal environment for this track; created with python -m venv
   |--dna
   |--dci

[cmlccie]

This way we could simply instruct participants to work out of the project root, and provide instructions relative to their project folder.

Activate your virtual environment?

source venv/bin/activate

Run a script?

python LM-XXXX/myscript.py

etc.

[annegentle]

Geez, yes, I hadn't realized it wasn't already this way. Agreed. We'll see what we can do in the next release set.

[annegentle]

@cmlccie I'm not entirely sure how to make these changes. Are these changes in dCloud images?

Also, help me understand what type of user would have cc, dna, and dci folders? Are many people completing all three tracks, or is this for image re-use purposes?

[annegentle]

This has been resolved in the DNAv3 work.