diff --git a/.gitignore b/.gitignore index 940794e..fdec681 100644 --- a/.gitignore +++ b/.gitignore @@ -1,288 +1,19 @@ -## Ignore Visual Studio temporary files, build results, and -## files generated by popular Visual Studio add-ons. -## -## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore +################################################################################ +# ignore mac os x and windows files +################################################################################ -# User-specific files -*.suo -*.user -*.userosscache -*.sln.docstates +Thumbs.db +.DS_Store +~\$* -# User-specific files (MonoDevelop/Xamarin Studio) -*.userprefs +################################################################################ +# ignore other files here +################################################################################ -# Build results -[Dd]ebug/ -[Dd]ebugPublic/ -[Rr]elease/ -[Rr]eleases/ -x64/ -x86/ -bld/ -[Bb]in/ -[Oo]bj/ -[Ll]og/ -# Visual Studio 2015 cache/options directory -.vs/ -# Uncomment if you have tasks that create the project's static files in wwwroot -#wwwroot/ -# MSTest test Results -[Tt]est[Rr]esult*/ -[Bb]uild[Ll]og.* +################################################################################ +# not ignore .gitignore +################################################################################ -# NUNIT -*.VisualState.xml -TestResult.xml - -# Build Results of an ATL Project -[Dd]ebugPS/ -[Rr]eleasePS/ -dlldata.c - -# .NET Core -project.lock.json -project.fragment.lock.json -artifacts/ -**/Properties/launchSettings.json - -*_i.c -*_p.c -*_i.h -*.ilk -*.meta -*.obj -*.pch -*.pdb -*.pgc -*.pgd -*.rsp -*.sbr -*.tlb -*.tli -*.tlh -*.tmp -*.tmp_proj -*.log -*.vspscc -*.vssscc -.builds -*.pidb -*.svclog -*.scc - -# Chutzpah Test files -_Chutzpah* - -# Visual C++ cache files -ipch/ -*.aps -*.ncb -*.opendb -*.opensdf -*.sdf -*.cachefile -*.VC.db -*.VC.VC.opendb - -# Visual Studio profiler -*.psess -*.vsp -*.vspx -*.sap - -# TFS 2012 Local Workspace -$tf/ - -# Guidance Automation Toolkit -*.gpState - -# ReSharper is a .NET coding add-in -_ReSharper*/ -*.[Rr]e[Ss]harper -*.DotSettings.user - -# JustCode is a .NET coding add-in -.JustCode - -# TeamCity is a build add-in -_TeamCity* - -# DotCover is a Code Coverage Tool -*.dotCover - -# Visual Studio code coverage results -*.coverage -*.coveragexml - -# NCrunch -_NCrunch_* -.*crunch*.local.xml -nCrunchTemp_* - -# MightyMoose -*.mm.* -AutoTest.Net/ - -# Web workbench (sass) -.sass-cache/ - -# Installshield output folder -[Ee]xpress/ - -# DocProject is a documentation generator add-in -DocProject/buildhelp/ -DocProject/Help/*.HxT -DocProject/Help/*.HxC -DocProject/Help/*.hhc -DocProject/Help/*.hhk -DocProject/Help/*.hhp -DocProject/Help/Html2 -DocProject/Help/html - -# Click-Once directory -publish/ - -# Publish Web Output -*.[Pp]ublish.xml -*.azurePubxml -# TODO: Comment the next line if you want to checkin your web deploy settings -# but database connection strings (with potential passwords) will be unencrypted -*.pubxml -*.publishproj - -# Microsoft Azure Web App publish settings. Comment the next line if you want to -# checkin your Azure Web App publish settings, but sensitive information contained -# in these scripts will be unencrypted -PublishScripts/ - -# NuGet Packages -*.nupkg -# The packages folder can be ignored because of Package Restore -**/packages/* -# except build/, which is used as an MSBuild target. -!**/packages/build/ -# Uncomment if necessary however generally it will be regenerated when needed -#!**/packages/repositories.config -# NuGet v3's project.json files produces more ignorable files -*.nuget.props -*.nuget.targets - -# Microsoft Azure Build Output -csx/ -*.build.csdef - -# Microsoft Azure Emulator -ecf/ -rcf/ - -# Windows Store app package directories and files -AppPackages/ -BundleArtifacts/ -Package.StoreAssociation.xml -_pkginfo.txt - -# Visual Studio cache files -# files ending in .cache can be ignored -*.[Cc]ache -# but keep track of directories ending in .cache -!*.[Cc]ache/ - -# Others -ClientBin/ -~$* -*~ -*.dbmdl -*.dbproj.schemaview -*.jfm -*.pfx -*.publishsettings -orleans.codegen.cs - -# Since there are multiple workflows, uncomment next line to ignore bower_components -# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622) -#bower_components/ - -# RIA/Silverlight projects -Generated_Code/ - -# Backup & report files from converting an old project file -# to a newer Visual Studio version. Backup files are not needed, -# because we have git ;-) -_UpgradeReport_Files/ -Backup*/ -UpgradeLog*.XML -UpgradeLog*.htm - -# SQL Server files -*.mdf -*.ldf -*.ndf - -# Business Intelligence projects -*.rdl.data -*.bim.layout -*.bim_*.settings - -# Microsoft Fakes -FakesAssemblies/ - -# GhostDoc plugin setting file -*.GhostDoc.xml - -# Node.js Tools for Visual Studio -.ntvs_analysis.dat -node_modules/ - -# Typescript v1 declaration files -typings/ - -# Visual Studio 6 build log -*.plg - -# Visual Studio 6 workspace options file -*.opt - -# Visual Studio 6 auto-generated workspace file (contains which files were open etc.) -*.vbw - -# Visual Studio LightSwitch build output -**/*.HTMLClient/GeneratedArtifacts -**/*.DesktopClient/GeneratedArtifacts -**/*.DesktopClient/ModelManifest.xml -**/*.Server/GeneratedArtifacts -**/*.Server/ModelManifest.xml -_Pvt_Extensions - -# Paket dependency manager -.paket/paket.exe -paket-files/ - -# FAKE - F# Make -.fake/ - -# JetBrains Rider -.idea/ -*.sln.iml - -# CodeRush -.cr/ - -# Python Tools for Visual Studio (PTVS) -__pycache__/ -*.pyc - -# Cake - Uncomment if you are using it -# tools/** -# !tools/packages.config - -# Telerik's JustMock configuration file -*.jmconfig - -# BizTalk build output -*.btp.cs -*.btm.cs -*.odx.cs -*.xsd.cs +!.gitignore \ No newline at end of file diff --git a/ApplicationModernization/.gitignore b/ApplicationModernization/.gitignore new file mode 100644 index 0000000..e69de29 diff --git a/DataModernization/.gitignore b/DataModernization/.gitignore new file mode 100644 index 0000000..e69de29 diff --git a/InfrastructureModernization/.gitignore b/InfrastructureModernization/.gitignore new file mode 100644 index 0000000..e69de29 diff --git a/PublishingGuidelines/LICENSE b/PublishingGuidelines/LICENSE new file mode 100644 index 0000000..2107107 --- /dev/null +++ b/PublishingGuidelines/LICENSE @@ -0,0 +1,21 @@ + MIT License + + Copyright (c) Microsoft Corporation. All rights reserved. + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in all + copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE diff --git a/PublishingGuidelines/README.md b/PublishingGuidelines/README.md new file mode 100644 index 0000000..d1d2663 --- /dev/null +++ b/PublishingGuidelines/README.md @@ -0,0 +1,153 @@ +# Microsoft Open Source Labs Publishing Guidelines + +## Table of Contents + + * [Microsoft Open Source Labs Publishing Guidelines](#microsoft-open-source-labs-publishing-guidelines) + * [Minimum Requirements](#minimum-requirements) + * [Content](#content) + * [TOC script](#toc-script) + * [How to create a lab repository?](#how-to-create-a-lab-repository) + * [Git repository best practices](#git-repository-best-practices) + * [Development Branch](#development-branch) + * [Staging Branch](#staging-branch) + * [Master Branch](#master-branch) + * [Tags / Deployments](#tags--deployments) + * [Deploy script](#deploy-script) + * [Contributing](#contributing) + + +## Minimum Requirements + +Each laboratory needs to include the following files as a minimum to be deployed: + +1. A *LICENSE* file with an MIT License template. +2. A *README.md* Markdown file with the description (step-by-step) of the laboratory. You can find a description of the Markdown syntax [here](https://guides.github.com/features/mastering-markdown/). +3. Any other supporting documents, file, source code, etc. + +## Storing of the labs + +### Naming conventions + +The laboratory name in the directory should be stored without any spaces or symbols in a Upercase first mode. For example the lab *Containers with ACS in Azure* name should be stored as `ContainersWithACSInAzure`. + +### Storage conventions + +Each lab should be stored in a separate folder structure in the repository inside one of the following directories: + +* ApplicationModernization +* InfrastructureModernization +* DataModernization + +For example a laboratory on *Containers with ACS in Azure* should be stored in `ApplicationModernization/ContainersWithACSInAzure`. + +## Content + +In order to maintain a standardized repository of laboratories, there is some content that needs to be included in every laboratory. This sections are required: + +
+ +
Table of Contents
+
The Table of Contents for the Laboratory document.
+ +
Overview and Pre-Requisites
+
An Overview of the scope of the lab, any pre-requisites and topics covered on the lab should be clearly explained here.
+ +
Laboratory section(s)
+
Here is where the content of the lab is added. Several sections and/or subsections can be added.
+ +
Conclusion
+
A conclusion detailing what was done and any follow-up steps.
+ +
End your Lab
+
Here it should be explained how to clear, delete and release any used resources so the user doesn't get billed after the lab.
+ +
Additional Resources and References
+
Any additional resource, links, references should be added here.
+ +
License
+
The licensing and copyright information
+ +
+ +#### TOC script + +The publishing guideline contains a script that will help you to create a **Table of Contents** from your MarkDown file. + +Please copy `scripts/gh-md-toc` script to the root of your lab repository, the script can be executed using the command: + + # ./gh-md-toc README.md + +This will output to screen a auto-generated table of contents that can be copy and pasted into your README.md file. + +## How to create a lab repository? + +As a team member you have access to create a new lab by cloning this repository and following the **Storage Conventions** for the lab. + +The initial skeleton of the lab should include the `skeleton/template.md` template file and the `LICENSE` file. + + +## Git repository best practices + +> Some of the best practices and recommendations described in this guide in terms of *Git Branching Strategy* are based from this model: [http://nvie.com/posts/a-successful-git-branching-model/](http://nvie.com/posts/a-successful-git-branching-model/) + +The branching strategy recommended to maintain your Lab follows a three-stages and tagging approach. + +In order to create a new branch, you can run the following command: + + # git branch -b NAME_OF_BRANCH + +In order to jump into your new branch, you can run the command: + + # git checkout NAME_OF_BRANCH + + +### Development Branch + +The `development` branch is the current *working* branch, current changes and updates will be done here. + + +### Staging Branch + +The `staging` branch will give us a *preview* of a new release of the lab. + +In order to commit your development changes from `development` to `staging`, you can use: + + # git checkout staging + # git merge --no-ff development + + +### Master Branch + +The `master` branch is the latest stable release of the lab. + + +### Tags / Deployments + +Each `master` branch commit needs to be `tagged`, so users can easily browse previous versions of the lab content. + + +#### Deploy script + +The publishing guideline contains a script that will help you automate the steps mentioned above to commit to the `master` branch and create a new tag/deployment. + +Please copy `scripts/deploy.sh` script to the root of your lab repository, the script can be executed using the command: + + # ./deploy.sh -v "NEW_VERSION" -m "COMMENT" + +Where `NEW_VERSION` is the name of the version or tag to be used and `COMMENT` is a note for the commit. + +## Contributing + +This project welcomes contributions and suggestions. Most contributions require you to agree to a +Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us +the rights to use your contribution. For details, visit https://cla.microsoft.com. + +When you submit a pull request, a CLA-bot will automatically determine whether you need to provide +a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions +provided by the bot. You will only need to do this once across all repos using our CLA. + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or +contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + +Please report any bug or issue on the labs trough the [GitHub Issues Page](https://github.com/Microsoft/OpenSourceLabs/issues) page. \ No newline at end of file diff --git a/PublishingGuidelines/scripts/deploy.sh b/PublishingGuidelines/scripts/deploy.sh new file mode 100644 index 0000000..3785801 --- /dev/null +++ b/PublishingGuidelines/scripts/deploy.sh @@ -0,0 +1,120 @@ +#!/bin/bash + +# This script will deploy to a branch model following best practices defined in +# http://nvie.com/posts/a-successful-git-branching-model/ +# +################################################################################# +# +# Instructions: +# +# Copy this script to the root directory of the repository +# Please be sure the master, staging and development branch exists +# Please execute the script for help: ./deploy.sh +# +################################################################################# +# +# License information: +# +# MIT License +# +# Copyright (c) 2016 OSS Labs +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. +# +# + +VERSION_FILE='VERSION' + +MASTER_BRANCH='master' +STAGING_BRANCH='staging' +DEV_BRANCH='development' + +# Get parameters needed +while [[ $# -gt 1 ]] +do +key="$1" + +case $key in + -m|--message) + MESSAGE="$2" + shift # past argument + ;; + -v|--version) + VERSION="$2" + shift # past argument + ;; + *) + # unknown option + ;; +esac +shift # past argument or value +done + +if [[ -z $MESSAGE || -z $VERSION ]]; then + echo 'Parameters missing...' + echo ' ' + echo ' Usage: ./deploy.sh -v "NEW_VERSION" -m "COMMENT"' + echo ' NEW_VERSION : New version/tag for the deployment' + echo ' COMMENT : Comment/Message for the commit of the deployment' + exit 1 +fi + +# Move to development branch +git checkout $DEV_BRANCH + +# Check that there are any changes to commit +if [[ `git status --porcelain` ]]; then + # changes we continue + echo "\nDeploying..." +else + # no changes + echo "\nNothing to commit, please modify something and proceed\n" +fi + +# Commit changes +git add . +git commit -m "$COMMENT" + +# Move to staging branch and merge development one +git checkout $STAGING_BRANCH +git merge --no-ff --no-edit $DEV_BRANCH + +# Updating version file +echo $VERSION > $VERSION_FILE + +# Commit changes for staging +git add . +git commit -m "Bumped version to $VERSION" + +# Move to master branch and merge staging one, tagging resources +git checkout $MASTER_BRANCH +git merge --no-ff --no-edit $STAGING_BRANCH +git tag -a $VERSION -m "$COMMENT" + +# Move to development branch and merge staging one +git checkout $DEV_BRANCH +git merge --no-ff --no-edit $STAGING_BRANCH + +# Commit All +git push --all +git push --tags + +echo "### All done ###" + +# END \ No newline at end of file diff --git a/PublishingGuidelines/scripts/gh-md-toc b/PublishingGuidelines/scripts/gh-md-toc new file mode 100644 index 0000000..c770ef2 --- /dev/null +++ b/PublishingGuidelines/scripts/gh-md-toc @@ -0,0 +1,194 @@ +#!/usr/bin/env bash + +## +## Cloned from: https://github.com/ekalinin/github-markdown-toc +## +## Dependencies: +## curl or wget +## awk (mawk, gawk is not supported) +## grep +## sed +## bats (for unit tests) +## + +# +# Steps: +# +# 1. Download corresponding html file for some README.md: +# curl -s $1 +# +# 2. Discard rows where no substring 'user-content-' (github's markup): +# awk '/user-content-/ { ... +# +# 3.1 Get last number in each row like ' ... sitemap.js.*<\/h/)+2, RLENGTH-5) +# +# 5. Find anchor and insert it inside "(...)": +# substr($0, match($0, "href=\"[^\"]+?\" ")+6, RLENGTH-8) +# + +gh_toc_version="0.4.7" + +gh_user_agent="gh-md-toc v$gh_toc_version" + +# +# Download rendered into html README.md by its url. +# +# +gh_toc_load() { + local gh_url=$1 + + if type curl &>/dev/null; then + curl --user-agent "$gh_user_agent" -s "$gh_url" + elif type wget &>/dev/null; then + wget --user-agent="$gh_user_agent" -qO- "$gh_url" + else + echo "Please, install 'curl' or 'wget' and try again." + exit 1 + fi +} + +# +# Converts local md file into html by GitHub +# +# ➥ curl -X POST --data '{"text": "Hello world github/linguist#1 **cool**, and #1!"}' https://api.github.com/markdown +#

Hello world github/linguist#1 cool, and #1!

'" +gh_toc_md2html() { + local gh_file_md=$1 + curl -s --user-agent "$gh_user_agent" \ + --data-binary @"$gh_file_md" -H "Content-Type:text/plain" \ + https://api.github.com/markdown/raw +} + +# +# Is passed string url +# +gh_is_url() { + if [[ $1 == https* || $1 == http* ]]; then + echo "yes" + else + echo "no" + fi +} + +# +# TOC generator +# +gh_toc(){ + local gh_src=$1 + local gh_src_copy=$1 + local gh_ttl_docs=$2 + + if [ "$gh_src" = "" ]; then + echo "Please, enter URL or local path for a README.md" + exit 1 + fi + + + # Show "TOC" string only if working with one document + if [ "$gh_ttl_docs" = "1" ]; then + + echo "Table of Contents" + echo "=================" + echo "" + gh_src_copy="" + + fi + + if [ "$(gh_is_url "$gh_src")" == "yes" ]; then + gh_toc_load "$gh_src" | gh_toc_grab "$gh_src_copy" + else + gh_toc_md2html "$gh_src" | gh_toc_grab "$gh_src_copy" + fi +} + +# +# Grabber of the TOC from rendered html +# +# $1 — a source url of document. +# It's need if TOC is generated for multiple documents. +# +gh_toc_grab() { + # if closed is on the new line, then move it on the prev line + # for example: + # was: The command foo1 + # + # became: The command foo1 + sed -e ':a' -e 'N' -e '$!ba' -e 's/\n<\/h/<\/h/g' | + # find strings that corresponds to template + grep -E -o '//' | sed 's/<\/code>//' | + # now all rows are like: + # ... .*<\/h/)+2, RLENGTH-5)"](" gh_url substr($0, match($0, "href=\"[^\"]+?\" ")+6, RLENGTH-8) ")"}' | sed 'y/+/ /; s/%/\\x/g')" +} + +# +# Returns filename only from full path or url +# +gh_toc_get_filename() { + echo "${1##*/}" +} + +# +# Options hendlers +# +gh_toc_app() { + local app_name="gh-md-toc" + + if [ "$1" = '--help' ] || [ $# -eq 0 ] ; then + echo "GitHub TOC generator ($app_name): $gh_toc_version" + echo "" + echo "Usage:" + echo " $app_name src [src] Create TOC for a README file (url or local path)" + echo " $app_name - Create TOC for markdown from STDIN" + echo " $app_name --help Show help" + echo " $app_name --version Show version" + return + fi + + if [ "$1" = '--version' ]; then + echo "$gh_toc_version" + return + fi + + if [ "$1" = "-" ]; then + if [ -z "$TMPDIR" ]; then + TMPDIR="/tmp" + elif [ -n "$TMPDIR" -a ! -d "$TMPDIR" ]; then + mkdir -p "$TMPDIR" + fi + local gh_tmp_md + gh_tmp_md=$(mktemp $TMPDIR/tmp.XXXXXX) + while read input; do + echo "$input" >> "$gh_tmp_md" + done + gh_toc_md2html "$gh_tmp_md" | gh_toc_grab "" + return + fi + + for md in "$@" + do + echo "" + gh_toc "$md" "$#" + done + + echo "" + echo "Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)" +} + +# +# Entry point +# +gh_toc_app "$@" diff --git a/PublishingGuidelines/skeleton/template.md b/PublishingGuidelines/skeleton/template.md new file mode 100644 index 0000000..40ad989 --- /dev/null +++ b/PublishingGuidelines/skeleton/template.md @@ -0,0 +1,58 @@ +# Laboratory Title + + +## Table of Contents + +The Table of Contents for the Laboratory document. + + +## Overview and Pre-Requisites + +An Overview of the scope of the lab, any pre-requisites and topics covered on the lab should be clearly explained here. + + +### Overview + +Overview of the lab. + + +### Pre-requisites + +Pre-requisites of the lab. + + +### Topics Covered + +Topics covered. + + +## Laboratory Section + +Here is where the content of the lab is added. Several sections and/or subsections can be added. + + +## Conclusion + +A conclusion detailing what was done and any follow-up steps. + + +## End your Lab + +Here it should be explained how to clear, delete and release any used resources so the user doesn't get billed after the lab. + + +## Additional Resources and References + +Any additional resource, links, references should be added here. + + +### Useful Links + +Any useful link for the user. + + +## License + +Copyright (c) Microsoft Corporation. All rights reserved. + +Licensed under the [MIT](LICENSE) License. \ No newline at end of file diff --git a/README.md b/README.md index 72f1506..dd30fff 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ +# Microsoft Open Source Labs Publishing Guidelines -# Contributing +## Contributing This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us @@ -12,3 +13,5 @@ provided by the bot. You will only need to do this once across all repos using o This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + +Please report any bug or issue on the labs trough the [GitHub Issues Page](https://github.com/Microsoft/OpenSourceLabs/issues) page. \ No newline at end of file