Package: azbacklog
Azure Backlog Generator (AzBacklog)Following repetitive processes and aligning all resources consistently can be a daunting task, and it can be common to overlook a step or make an incorrect assumption. There are many variables to consider in any complex process—identifying roles, resources, etc.When conducting intense processes, it can be helpful to have a list of tasks to direct efforts. The Azure Backlog Generator (AzBacklog) is designed to build backlogs for complex processes based onproven practices. The backlogs can be generated in either Azure DevOps or GitHub.Currently Supported BacklogsAzBacklog currently supports creating backlogs for the following processes.BacklogCommand-line Option (see below:-b)Cloud Adoption Framework (CAF)cafEnterprise-scale Architectureesa(Coming Soon)Team Foundation Server (TFS) to Azure DevOpstfsExecutionPrior to execution, please take a moment to fully read through the documentation below.InstallationFirst, install theazbacklogpackage:pipinstallazbacklogNOTE:The library installs additional data files (the workitems) into a artifacts folder that your user may not have access to under the normal user permissions. MAC users using Homebrew may especially have this issue. In this case, instead of usingsudoto install the package, use the--userto install the package into the localized user's libary (ex:pip install azbacklog --user). Finally, by installing to the localized user's path, you may need to add the path's binary folder to Python's search path.Create a BacklogTo create a backlog:./azbacklog -t TOKEN


usage: azbacklog [-h] -t TOKEN [-r {azure,github}] [-p PROJECT] [-o ORG] [-b {caf,tfs}]

Generate a backlog of work items.

required arguments:
  -t TOKEN, --token TOKEN                           GitHub or Azure DevOps token

optional arguments:
  -h, --help                                        show this help message and exit
  -r {azure,github}, --repo {azure,github}          targetted repository type
  -p PROJECT, --project PROJECT                     project (repository) name to create
  -o ORG, --org ORG                                 REQUIRED. if target is Azure DevOps
                                                    OPTIONAL. if a GitHub organization
  -b {caf,esa}, --backlog {caf,esa}                 type of backlog to createDevelopmentTo contribute to the project from your development environment:git clone https://github.com/Azure/Azure-Backlog-Generator generator
cd generator

pip install -e .[dev]The previous commands will clone the repo and not only install the runtime dependencies but also the development dependencies.Executing Locally Under DevelopmentOnce you've installed the package locally (e.g.-e .[dev]in the previous command), executing the package is as simple as (include the necessary parameters outlined above in theCreate a Backlogsection):./azbacklogRunning TestsTo simply execute unit tests:python-mpytestIf you would like to view a coverage report of the unit tests:# Generate the report using pytestcoveragerun-mpytest# View the report, including missing linescoveragereport-mShared ResponsibilityMicrosoft maintains a position of shared responsibility between itself and the customer. Under this shared responsibility, it is understood that appropriate cloud adoption requires active participation from the architect(s) involved and the customer unit(s). In this process, the customer should be prepared to make available network and identity administrators, application and data architects, and other security principals. By understanding requirements through active feedback, Microsoft and its technical architects can adequately assess customer needs and propose recommendations that are proven in practice and that successfully meet customer objectives.Technical RequirementsThe scripts in this repository require Python as they rely on native Azure DevOps and GitHub SDKs. To execute these scripts, pleasedownload Python.Technical GuidelinesBelow are the technical guidelines that should be followed when contributing to the project.SourceThe application, including unit tests, are developed in Python in order to maintain compatibility between Azure DevOps and GitHub SDKs. The backlog items are developed in simple JSON format with very little metadata.Backlog ItemsThe backlog items are arranged in a collection of epics, features, stories and tasks with the necessary parent-child relationships. The following table outlines the correlations between the backlog items in Azure DevOps and GitHub.Azure DevOpsGitHub IssuesEpicProjectFeatureMilestoneUser StoryIssueTaskChecklist in the body of the IssueExcluding the specific git action of 'tagging' a commit,tagshave differing nomenclature between Azure DevOps and GitHub. In Azure DevOps, tags are associated with work items whereas, in GitHub, the terminology for tags is "labels." That being the case, and based on the previous table, tags will be associated with all work item types in Azure DevOps, but will only be associated with issues in GitHub.AzBacklog will create tags, as applicable, in both platforms--Azure DevOps and GitHub.Creating Custom BacklogsContributors are welcome to create new backlogs that others may find useful for repititive actions. The following sections will explain the process.Directory StructureThe directory structure follows a very simplistic heirarchy to fascilitate dependency creation and increase efficiency by minimizing overhead:.
├── src                         (source code)
├── tests                       (unit tests)
└── workitems
    └── backlog_type
        ├── config.json         (specific backlog configuration)
        ├── README.md           (optional. README.md for repo initialization)
        ├── 01_SampleEpic1
        │   ├── metadata.json
        │   └── 01_SampleFeature1
        │       ├── metadata.json
        │       └── 01_SampleStory1
        │           ├── metadata.json
        │           ├── 01_SampleTask1
        │            │   └── metadata.json
        │            └── 02_SampleTask2
        │                └── metadata.json
        └── 02_SampleEpic2
            ├── metadata.json
            ├── 01_SampleFeature1
            │   ├── metadata.json
            │   └── 01_SampleStory1
            │       ├── metadata.json
            │       └── 01_SampleTask1
            │           └── metadata.json
            └── 02_SampleFeature2
                ├── metadata.json
                └── 01_SampleStory1
                    ├── metadata.json
                    ├── 01_SampleTask1
                    │   └── metadata.json
                    └── 02_SampleTask2
                        └── metadata.jsonThe heirarchy above follows the structure ofEpic -> Feature -> User Story -> Task. Each backlog type must contain aconfig.jsonthat directs the engine's creation process. Each folder will contain ametadata.jsonfile that follows theWork Item Formatbelow and child items. Task folders will not contain any child work items and should only contain its metadata. Finally, the top folder for each backlog type may contain aREADME.mdthat will be used upon repository initialization.Config.json FormatThe format of the backlog'sconfig.jsonfile is the following:{"description":"My backlog","tags":["Strategy","Plan","Ready","Innovation","Migration","First Workload","First Host","Workload Template"],"roles":["Infra","AppDev","Data","Security"],"tagcolors":["d73a4a","0075ca","cfd3d7","a2eeef","7057ff","008672","e4e669","d876e3","39db61","f2639a","59b5d6","12487a"]}OPTIONSdescriptionRequired.A simple, single-line description of the backlog.tagsRequired.Allowed tags that may be used for the work items. Tags can be used to group similar work item types.rolesRequired.Allowed roles that may be used for the work items. Roles can be used to easily identify team individuals who should be assigned to the work item.tagcolorsOptional.Hexidecimal colors to be used for each tag and role. Standard colors can be used for easier identification based on business process.NOTES: 1) The total number oftagcolorsmust equal the combined sum of thetagsandroles. 2)tagcolorsare not required when deploying to Azure DevOps, but are required for GitHub deployments.Work Item FormatThe format of a work item'smetadata.jsonfile is the following:{"title":"Work Item Title","description":"Some description of the work item","tag":["Strategy | Plan | Ready"],"roles":["AppDev"]}OPTIONStitleRequired.A simple, single-line title of the work item.descriptionRequired.The content of the work item.tagsRequired.The tag(s) for the specific work item.rolesRequired.The role(s) for the specific work item.NOTE:TagsandRolesmust be those provided in the respective list of the corresponding process. The available lists are found with thebacklog descriptions.ContributingYour experience and feedback are valuable and, therefore, your contributions are welcomed. Please create necessary issues and, optionally, pull requests for your feedback or contributions. Please adhere to the technical guidelines above when contributing to the source code.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, visithttps://cla.opensource.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., status check, 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 theMicrosoft Open Source Code of Conduct.
For more information see theCode of Conduct FAQor
contactopencode@microsoft.comwith any additional questions or comments.