Microsoft-OpenSource-Labs/publishing-guidelines

Microsoft Open Source Labs Publishing Guidelines

Microsoft Open Source Labs Publishing Guidelines

Table of Contents

• Microsoft Open Source Labs Publishing Guidelines
  • Minimum Requirements
  • Content
    • TOC script
  • How to create a lab repository?
  • Git repository best practices
    • Development Branch
    • Staging Branch
    • Master Branch
    • Tags / Deployments
      • Deploy script
  • 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 of the laboratory. You can find a description of the Markdown syntax here.
   • You can use Pandoc to convert your docx file to Markdown.
3. A Word file with the description of the laboratory.
4. A PDF file with the description of the laboratory.
5. Any other supporting documents, file, source code, etc.

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?

Please send an email to emeaosslabs@microsoft.com with the repository name, the tile for the lab, a short description of the lab and your GitHub personal username. We will create the repository and it will be initialized with an initial skeleton and you will be added to the list of GitHub contributors for the repo.

The initial skeleton of the lab will include a License file, an empty template Word document, a template Markdown Readme file and a gitignore 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/

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

If you want to contribute to a laboratory, you can follow the GitHub guidelines in how to contribute to a project: https://guides.github.com/activities/contributing-to-open-source/#contributing.

Also, is possible to report a bug or issue on the lab trough the GitHub Issues page.