diff --git a/.github/ISSUE_TEMPLATE/community-report.md b/.github/ISSUE_TEMPLATE/community-report.md new file mode 100644 index 000000000..86cbfa65c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/community-report.md @@ -0,0 +1,91 @@ +--- +name: Community Report Contribution +about: Submit a community Power BI report to the FinOps toolkit +title: '[Community Report] ' +labels: 'community-report, Needs: Triage 🔍' +--- + +# Community Report Contribution + +Thank you for contributing a Power BI report to the FinOps toolkit community! 🙌 + +## 📋 Report information + +**Report Name:** + +**Author:** + +**Contact:** + +**Brief Description:** + +**Target Audience:** + +**FinOps Capability:** + +## ✅ Pre-submission checklist + +I confirm that my report submission includes: + +### Required files +- [ ] README.md with all required sections completed +- [ ] CONTRIBUTORS.md with technical lead information +- [ ] Power BI report files (.pbip, .pbit, or .pbix) +- [ ] At least 2 screenshots in the images/ folder + +### Documentation +- [ ] Clear setup instructions for data sources +- [ ] Prerequisites and requirements listed +- [ ] Known limitations documented +- [ ] Troubleshooting guidance included + +### Quality +- [ ] Report has been tested with real data +- [ ] All sensitive data has been removed +- [ ] Report works with latest Power BI Desktop +- [ ] Data source connections are parameterized + +### Licensing +- [ ] Report is licensed under MIT or compatible license +- [ ] All third-party components are properly attributed +- [ ] No copyrighted content without permission + +### Commitment +- [ ] I commit to serving as technical lead for this report +- [ ] I understand the [technical lead responsibilities](https://github.com/microsoft/finops-toolkit/blob/dev/docs-wiki/Advisory-council.md) +- [ ] I will respond to issues and maintain the report + +## 📂 Report location + +**Folder path:** `src/power-bi/community/[your-report-name]/` + +**Files included:** +- + +## 📷 Screenshots + + + +## 📝 Additional notes + + + +--- + +## For reviewers + +### Review checklist + +- [ ] Folder structure follows template guidelines +- [ ] README.md is complete and clear +- [ ] CONTRIBUTORS.md includes technical lead contact +- [ ] Screenshots are included and descriptive +- [ ] No sensitive data in report files +- [ ] Report files are in correct format +- [ ] Documentation quality is acceptable +- [ ] License is compatible with MIT +- [ ] Report has been tested (as stated by contributor) + +### Review notes + + diff --git a/docs-mslearn/toolkit/changelog.md b/docs-mslearn/toolkit/changelog.md index 7c5d94e4b..105a208ea 100644 --- a/docs-mslearn/toolkit/changelog.md +++ b/docs-mslearn/toolkit/changelog.md @@ -43,6 +43,8 @@ The following section lists features and enhancements that are currently in deve ### [Power BI reports](power-bi/reports.md) v13 +- **Added** + - Created [community reports repository](power-bi/community.md) for community-contributed Power BI reports, similar to Azure Quickstart Templates. The repository enables the FinOps community to share specialized reports for specific use cases while maintaining clear differentiation from official toolkit reports. - **Fixed** - Fixed tag expansion in Power BI reports when tag names contain special characters like colons. diff --git a/docs-mslearn/toolkit/power-bi/community.md b/docs-mslearn/toolkit/power-bi/community.md new file mode 100644 index 000000000..33534ac0d --- /dev/null +++ b/docs-mslearn/toolkit/power-bi/community.md @@ -0,0 +1,185 @@ +--- +title: Community Power BI reports +description: Learn about community-contributed Power BI reports for FinOps in the FinOps toolkit and how to contribute your own reports. +author: flanakin +ms.author: micflan +ms.date: 10/10/2025 +ms.topic: how-to +ms.service: finops +ms.subservice: finops-toolkit +ms.reviewer: micflan +#customer intent: As a FinOps practitioner, I want to discover and use community-contributed Power BI reports to accelerate my FinOps journey. +--- + +# Community Power BI reports + +The FinOps toolkit includes a repository for community-contributed Power BI reports. These reports are created and maintained by FinOps practitioners like you to address specialized use cases, industries, or scenarios that complement the official toolkit reports. + +
+ +On this page: + +- [About community reports](#about-community-reports) +- [Available community reports](#available-community-reports) +- [Using community reports](#using-community-reports) +- [Contributing a report](#contributing-a-report) +- [Support and maintenance](#support-and-maintenance) + +--- + +## About community reports + +Community reports are Power BI reports contributed by members of the FinOps community. These reports provide specialized solutions for specific scenarios that may not be covered by the [official FinOps toolkit reports](reports.md). + +### Key differences from official reports + +The following table compares community reports to official FinOps toolkit reports: + +| Aspect | Official toolkit reports | Community reports | +|--------|-------------------------|-------------------| +| **Maintenance** | Maintained by the FinOps toolkit team | Maintained by community contributors | +| **Support** | Supported through Microsoft channels | No formal support guarantee | +| **Quality assurance** | Full QA and testing by toolkit team | Community reviewed, best effort | +| **Updates** | Regular updates with toolkit releases | Updated by report owners | +| **Branding** | FinOps toolkit branding | Community contributor branding | +| **SLA** | Best effort support | No SLA | + +> [!IMPORTANT] +> Community reports are provided "AS IS" without warranty of any kind. Microsoft and the FinOps toolkit team do not guarantee the quality, compatibility, performance, or ongoing maintenance of community reports. Each report is the responsibility of its contributor. + +
+ +## Available community reports + +> [!NOTE] +> No community reports have been submitted yet. Be the first to contribute! + +To view all available community reports: + +1. Browse the [community reports directory](https://github.com/microsoft/finops-toolkit/tree/dev/src/power-bi/community) on GitHub +2. Each report has its own folder containing: + - README.md with setup instructions and documentation + - Power BI report files (.pbip, .pbit, or .pbix) + - Screenshots and sample data (if applicable) + - CONTRIBUTORS.md with maintainer contact information + +
+ +## Using community reports + +To use a community report: + +### 1. Review the report documentation + +Before downloading a community report, review the report's README.md file to understand: + +- What the report does and who it's designed for +- Data sources and prerequisites required +- Known limitations or compatibility requirements +- Support expectations from the report maintainer + +### 2. Download the report + +Download the report files from the GitHub repository: + +1. Navigate to the [community reports directory](https://github.com/microsoft/finops-toolkit/tree/dev/src/power-bi/community) +2. Select the report you want to use +3. Download the report files: + - Use the .pbit file for first-time setup (template with no data) + - Use the .pbix file to preview with sample data (if available) + - Use the .pbip folder for source control and collaboration + +### 3. Configure data sources + +Follow the setup instructions in the report's README.md file to: + +1. Configure required data sources (Cost Management exports, FinOps hubs, etc.) +2. Set up authentication +3. Enter any required parameters +4. Refresh the data + +### 4. Customize as needed + +Community reports are designed to be customized for your specific needs: + +- Adjust filters and parameters +- Modify visuals and layouts +- Add your own data sources +- Integrate with other reports + +
+ +## Contributing a report + +We welcome contributions from the FinOps community! If you've created a Power BI report that could benefit others, consider contributing it to the toolkit. + +### Before you contribute + +Review the [contribution guidelines](https://github.com/microsoft/finops-toolkit/blob/dev/src/power-bi/community/README.md#-contribution-guidelines) to ensure your report meets the requirements: + +- Report must be well-documented with setup instructions +- Must include screenshots and sample data or configuration +- Must be tested with real data +- Must be licensed under MIT or compatible license +- You must commit to maintaining the report as technical lead + +### How to contribute + +1. Fork the [finops-toolkit repository](https://github.com/microsoft/finops-toolkit) +2. Create a new branch for your report +3. Copy the [report template](https://github.com/microsoft/finops-toolkit/tree/dev/src/power-bi/community/.template) to a new folder +4. Add your report files and documentation following the template structure +5. Submit a pull request with a clear description +6. Respond to review feedback from the community + +For detailed contribution steps, see the [community reports contribution guide](https://github.com/microsoft/finops-toolkit/blob/dev/src/power-bi/community/README.md#-contributing-a-report). + +
+ +## Support and maintenance + +### Getting support + +Community reports follow a community support model similar to [Azure Quickstart Templates](https://github.com/Azure/azure-quickstart-templates): + +1. **Check the report's README** for troubleshooting guidance and FAQs +2. **Contact the report maintainer** listed in the report's CONTRIBUTORS.md file +3. **Search existing issues** on GitHub for similar problems and solutions +4. **Open a new issue** on GitHub with the `community-report` label if needed +5. **Ask in discussions** for community help and suggestions + +### Reporting issues + +When reporting issues with a community report: + +1. Include the report name in the issue title +2. Tag the issue with `community-report` and `Type: Bug 🐛` labels +3. Mention the report maintainer from the CONTRIBUTORS.md file +4. Provide detailed reproduction steps, screenshots, and error messages +5. Include your Power BI Desktop version and data source configuration + +### Maintenance responsibilities + +Report contributors serve as technical leads for their reports and are responsible for: + +- Responding to issues and questions from users +- Maintaining compatibility with the latest Power BI versions +- Updating documentation as needed +- Reviewing and merging pull requests from other contributors +- Archiving or marking reports as deprecated if no longer maintained + +
+ +## Related content + +- [Official Power BI reports](reports.md) +- [Help me choose a data source](help-me-choose.md) +- [Set up Power BI reports](setup.md) +- [FinOps toolkit contribution guide](../help/contributors.md) +- [FinOps Framework](https://www.finops.org/framework/) + +
+ +--- + +_Community reports are maintained by their contributors and are not officially supported by Microsoft or the FinOps toolkit team. For supported reports, see [Power BI reports](reports.md)._ diff --git a/docs-mslearn/toolkit/power-bi/reports.md b/docs-mslearn/toolkit/power-bi/reports.md index 2c7cea800..917566f49 100644 --- a/docs-mslearn/toolkit/power-bi/reports.md +++ b/docs-mslearn/toolkit/power-bi/reports.md @@ -43,6 +43,13 @@ In addition, the following reports use the Cost Management connector for Power B - [Cost Management connector](connector.md) – Summarizes costs, savings, and commitment discounts using the Cost Management connector for Enterprise Agreements and Microsoft Customer Agreement accounts. - [Cost Management template app](template-app.md) (EA only) – The original Cost Management template app as a customizable .pbix file. +### Community reports + +The FinOps community also contributes specialized Power BI reports for specific use cases and industries. Community reports are maintained by their contributors and are not officially supported by the FinOps toolkit team. + +> [!div class="nextstepaction"] +> [Explore community reports](community.md) +
## Data sources diff --git a/docs/power-bi.md b/docs/power-bi.md index a9dae9a1c..839f37455 100644 --- a/docs/power-bi.md +++ b/docs/power-bi.md @@ -200,6 +200,7 @@ Create a new or update an existing FinOps hub instance. About the reports +Community reports 💜 Give feedback
diff --git a/src/power-bi/README.md b/src/power-bi/README.md index 9cbc3ca4c..9386f8844 100644 --- a/src/power-bi/README.md +++ b/src/power-bi/README.md @@ -4,6 +4,7 @@ On this page: - [īŋŊ Prerequisites](#-prerequisites) - [📐 Design guidelines](#-design-guidelines) +- [🌐 Community reports](#-community-reports) - [ℹī¸ Cost Management template app](#ℹī¸-cost-management-template-app) --- @@ -71,6 +72,17 @@ Power BI reports in the FinOps toolkit must adhere to the following guidelines:
+## 🌐 Community reports + +In addition to official FinOps toolkit reports, the community has contributed specialized reports for specific use cases and industries. Community reports are maintained by their contributors and provided "AS IS" without formal support from the FinOps toolkit team. + +For a full list of available community reports and contribution guidelines, see the [community reports directory](community/README.md). + +> [!IMPORTANT] +> Community reports are not officially maintained by the FinOps toolkit team. Each report is the responsibility of its contributor. Quality, compatibility, and ongoing maintenance may vary. + +
+ ## ℹī¸ Cost Management template app The Cost Management template app is managed by the Cost Management team. The template app is not available for download and cannot be edited. We are including this report in the FinOps toolkit to help unblock customers who are looking for something specific in this report, however we highly recommend using the FinOps toolkit reports instead. diff --git a/src/power-bi/community/.gitkeep b/src/power-bi/community/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/src/power-bi/community/.template/CONTRIBUTORS.md b/src/power-bi/community/.template/CONTRIBUTORS.md new file mode 100644 index 000000000..18f346c4b --- /dev/null +++ b/src/power-bi/community/.template/CONTRIBUTORS.md @@ -0,0 +1,37 @@ +# Contributors + +This file lists the contributors and maintainers for this community report. + +## Technical lead + +**Name:** [Your Name] +**Organization:** [Your Organization] +**GitHub:** [@your-github-handle](https://github.com/your-github-handle) +**Contact:** [Email or preferred contact method] +**Role:** Primary maintainer and technical lead + +## Additional contributors + + + +**Name:** [Contributor Name] +**Organization:** [Organization] +**GitHub:** [@github-handle](https://github.com/github-handle) +**Contribution:** [Brief description of contribution] + +--- + + + +## Acknowledgments + + + +- [Resource or person to acknowledge] +- [Resource or person to acknowledge] + +
+ +--- + +_For questions about this report, please contact the technical lead listed above._ diff --git a/src/power-bi/community/.template/INFO.md b/src/power-bi/community/.template/INFO.md new file mode 100644 index 000000000..77444b67b --- /dev/null +++ b/src/power-bi/community/.template/INFO.md @@ -0,0 +1,69 @@ +# Community Report Template + +This directory contains template files for contributing a community Power BI report to the FinOps toolkit. + +## How to use this template + +1. **Copy this template directory** to a new folder under `src/power-bi/community/` with your report name + - Use lowercase with hyphens (e.g., `advanced-chargeback`) + +2. **Update README.md** with your report details + - Replace all `[placeholder text]` with your actual content + - Remove sections that don't apply + - Add screenshots in the `images/` folder + +3. **Update CONTRIBUTORS.md** with your information + - Add yourself as the technical lead + - List any additional contributors + - Add acknowledgments if applicable + +4. **Add your report files** + - Power BI Project (.pbip) format is preferred + - Include .pbit template file + - Optionally include .pbix with sample data + - Remove any sensitive information + +5. **Create images folder** and add screenshots + ```bash + mkdir images + ``` + - Include at least 2-3 screenshots of key pages + - Use descriptive filenames (e.g., `overview-page.png`) + +6. **Review the checklist** in the main README.md to ensure your report meets all requirements + +7. **Submit a pull request** with your community report + +## File structure + +Your completed report directory should look like this: + +``` +your-report-name/ +├── README.md # Required: Your report documentation +├── CONTRIBUTORS.md # Required: Contributor information +├── images/ # Required: Screenshots +│ ├── screenshot-overview.png +│ └── screenshot-detail.png +├── report.pbip/ # Recommended: Power BI Project +│ ├── report.pbip +│ ├── definition/ +│ └── ... +├── report.pbit # Recommended: Template file +└── report.pbix # Optional: File with sample data +``` + +## Questions? + +If you have questions about contributing a community report: + +1. Review the [contribution guidelines](../README.md#-contribution-guidelines) in the main community README +2. Check existing community reports for examples +3. Ask in [GitHub Discussions](https://github.com/microsoft/finops-toolkit/discussions) +4. Open an issue with the `question` label + +
+ +--- + +_Thank you for contributing to the FinOps toolkit community!_ diff --git a/src/power-bi/community/.template/README.md b/src/power-bi/community/.template/README.md new file mode 100644 index 000000000..c30265045 --- /dev/null +++ b/src/power-bi/community/.template/README.md @@ -0,0 +1,212 @@ +# [Report Name] + +> [!NOTE] +> This is a **community report** maintained by [contributor name/organization]. It is not an official FinOps toolkit report and is provided "AS IS" without warranty. For questions or issues, please contact the maintainer listed in CONTRIBUTORS.md. + +**Last updated:** YYYY-MM-DD +**Author:** [Your Name or Organization] +**Contact:** [GitHub handle or email] + +
+ +## Overview + +[Provide a clear, concise description of what this report does and who it's for. Include the specific FinOps use case or capability this report addresses.] + +### FinOps use case + +**Primary capability:** [e.g., Cost allocation, Rate optimization, Workload optimization] +**Target persona:** [e.g., FinOps practitioners, Engineering teams, Finance teams] +**Industry/scenario:** [e.g., General purpose, SaaS companies, Enterprises with chargebacks] + +### Key features + +- [Feature 1: e.g., Chargeback by department with custom allocation rules] +- [Feature 2: e.g., Trend analysis across multiple subscriptions] +- [Feature 3: e.g., Integration with custom tagging strategy] +- [Add more features as needed] + +
+ +## Screenshots + +[Include 2-3 screenshots showcasing the key pages/features of your report] + +![Report overview](images/screenshot-overview.png) +_Caption describing what this page shows_ + +![Detailed view](images/screenshot-detail.png) +_Caption describing what this page shows_ + +
+ +## Prerequisites + +Before using this report, ensure you have: + +- **Power BI Desktop** - [Download latest version](https://powerbi.microsoft.com/desktop/) +- **Power BI license** - [Specify: Free, Pro, or Premium required] +- **Data sources configured** - [List required data sources] + - Cost Management exports (FOCUS format) - Required + - [Any other data sources] +- **Azure access** - [Specify required permissions] +- **[Any other prerequisites]** + +
+ +## Data sources + +This report connects to the following data sources: + +### Primary data source + +**[Data Source Name]** (e.g., Cost Management FOCUS exports) +- **Type:** [e.g., Azure Data Lake Storage, Azure Data Explorer] +- **Required exports:** [e.g., Cost and usage (FOCUS), Price sheet] +- **Configuration:** [Brief description or link to setup guide] + +### Additional data sources (if applicable) + +**[Additional Data Source]** +- **Type:** [Source type] +- **Purpose:** [Why this data is needed] +- **Configuration:** [Setup instructions] + +
+ +## Setup instructions + +Follow these steps to configure and use this report: + +### 1. Download the report + +Download the report files from this directory: +- `report.pbit` - Power BI template file (recommended for first-time setup) +- `report.pbix` - Power BI file with sample data (for preview) + +### 2. Configure data sources + +[Provide detailed step-by-step instructions for setting up data sources] + +1. Open the .pbit file in Power BI Desktop +2. When prompted, enter the following parameters: + - **Storage URL:** The DFS endpoint of your storage account (e.g., `https://mystorageaccount.dfs.core.windows.net`) + - **[Parameter 2]:** [Description] + - **[Parameter 3]:** [Description] + +### 3. Authenticate to data sources + +[Explain how to authenticate to each data source] + +1. When prompted, select the authentication method: + - For storage accounts: Use **Account key** or **Organizational account** + - [Other data sources] +2. Click **Connect** + +### 4. Refresh the data + +[Explain the refresh process] + +1. Click **Refresh** in the Home ribbon +2. Wait for the refresh to complete (this may take [estimated time] depending on data volume) + +### 5. Customize the report (optional) + +[Explain any customization options] + +- **Filters:** [How to configure filters] +- **Parameters:** [How to adjust parameters] +- **Visuals:** [How to customize visuals] + +
+ +## Report pages + +Brief description of each page in the report: + +### [Page 1 Name] + +[Description of what this page shows and how to use it] + +### [Page 2 Name] + +[Description of what this page shows and how to use it] + +### [Additional pages...] + +
+ +## Known limitations + +- **Limitation 1:** [e.g., Performance may degrade with datasets larger than 10GB] +- **Limitation 2:** [e.g., Requires specific tag structure (Department, Project, Environment)] +- **Limitation 3:** [e.g., Custom visuals may require separate installation] +- [Add any other limitations or known issues] + +
+ +## Troubleshooting + +### Common issues + +**Issue: [Common problem users might encounter]** +- **Cause:** [Why this happens] +- **Solution:** [How to fix it] + +**Issue: [Another common problem]** +- **Cause:** [Why this happens] +- **Solution:** [How to fix it] + +### Getting help + +If you encounter issues not covered here: + +1. Check the [FinOps toolkit documentation](https://aka.ms/finops/toolkit) +2. Review [closed issues](https://github.com/microsoft/finops-toolkit/issues?q=is%3Aissue+is%3Aclosed+label%3Acommunity-report) for similar problems +3. Contact the report maintainer (see CONTRIBUTORS.md) +4. Open a [new issue](https://github.com/microsoft/finops-toolkit/issues/new/choose) with the `community-report` label + +
+ +## Support and maintenance + +This report is maintained by the community contributor(s) listed in CONTRIBUTORS.md. + +- **Maintainer:** [Name/Organization] +- **Contact:** [GitHub handle or email] +- **Response time:** [e.g., Best effort, typically within 1 week] +- **Update frequency:** [e.g., Quarterly, as needed] + +For issues, questions, or feature requests, please contact the maintainer or open an issue on GitHub. + +
+ +## Version history + +### [Current Version] - YYYY-MM-DD + +- Initial release +- [Key features or changes] + + + +
+ +## License + +This report is licensed under the [MIT License](../../../../LICENSE), consistent with the FinOps toolkit. + +
+ +## Acknowledgments + +[Optional: Credit any third-party resources, inspirations, or contributors] + +- [Resource or person to acknowledge] +- [Resource or person to acknowledge] + +
+ +--- + +_This is a community-contributed report. It is not officially maintained by Microsoft or the FinOps toolkit team. For official reports, see the [FinOps toolkit Power BI reports](../../README.md)._ diff --git a/src/power-bi/community/README.md b/src/power-bi/community/README.md new file mode 100644 index 000000000..5c0fa4a58 --- /dev/null +++ b/src/power-bi/community/README.md @@ -0,0 +1,216 @@ +# 🌐 Community Power BI reports + +Welcome to the FinOps toolkit community reports repository! This is a collection of Power BI reports contributed and maintained by the FinOps community. These reports are designed to accelerate your FinOps journey by providing specialized reporting solutions for various use cases. + +
+ +On this page: + +- [📋 About community reports](#-about-community-reports) +- [🔍 Available reports](#-available-reports) +- [🤝 Contributing a report](#-contributing-a-report) +- [📐 Contribution guidelines](#-contribution-guidelines) +- [✅ Validation requirements](#-validation-requirements) +- [⚖ī¸ License and support](#ī¸-license-and-support) + +--- + +## 📋 About community reports + +Community reports are Power BI reports contributed by FinOps practitioners like you. These reports complement the official FinOps toolkit reports by providing specialized solutions for specific use cases, industries, or scenarios. + +### Key differences from official reports + +| Aspect | Official toolkit reports | Community reports | +|--------|-------------------------|-------------------| +| **Maintenance** | Maintained by the FinOps toolkit team | Maintained by community contributors | +| **Support** | Supported through toolkit channels | No formal support guarantee | +| **Quality assurance** | Full QA and testing by toolkit team | Community reviewed, best effort | +| **Updates** | Regular updates with toolkit releases | Updated by report owners | +| **Branding** | FinOps toolkit branding | Community contributor branding | + +> [!IMPORTANT] +> Community reports are provided "AS IS" without warranty of any kind. The FinOps toolkit team does not guarantee the quality, compatibility, performance, or ongoing maintenance of community reports. Each report is the responsibility of its contributor. + +
+ +## 🔍 Available reports + +The following reports are available in this directory. Each report is maintained by its contributor and may have different levels of maturity, support, and compatibility. + +> [!NOTE] +> No community reports have been submitted yet. Be the first to contribute! + +To browse all community reports, navigate to the subdirectories in this folder. Each report has its own folder with: +- README.md - Report documentation and setup instructions +- Power BI report files (.pbip, .pbit, or .pbix) +- Sample data (if applicable) +- Contributor contact information + +
+ +## 🤝 Contributing a report + +We welcome contributions from the FinOps community! If you've created a Power BI report for FinOps that could benefit others, we encourage you to share it here. + +### Before you contribute + +1. **Review the contribution guidelines** below to ensure your report meets the requirements. +2. **Test your report thoroughly** with real data to ensure it works as expected. +3. **Document your report** with clear setup instructions and data source requirements. +4. **Be prepared to maintain your report** as the technical lead and respond to issues from users. + +### How to submit a report + +1. **Fork the repository** and create a new branch for your report. +2. **Create a folder** under `src/power-bi/community/` with your report name (use lowercase with hyphens, e.g., `chargeback-advanced`). +3. **Add your report files** following the structure outlined in the contribution guidelines. +4. **Submit a pull request** with a clear description of your report and its use case. +5. **Respond to review feedback** from the community and toolkit team. + +
+ +## 📐 Contribution guidelines + +To maintain consistency and quality across community reports, please follow these guidelines: + +### Folder structure + +Each community report must be in its own folder with the following structure: + +``` +src/power-bi/community/ +└── your-report-name/ + ├── README.md # Required: Report documentation + ├── report.pbip/ # Recommended: Power BI Project format + │ └── ... + ├── report.pbit # Alternative: Power BI template file + ├── report.pbix # Alternative: Power BI file with sample data + ├── images/ # Optional: Screenshots and diagrams + │ └── screenshot.png + └── CONTRIBUTORS.md # Required: Contributor information +``` + +### Required files + +#### README.md + +Your report's README.md must include: + +1. **Report title and description** - What the report does and who it's for +2. **Author information** - Your name/organization and contact info +3. **Last updated date** - When the report was last modified +4. **FinOps use case** - Which FinOps capability or persona this addresses +5. **Data sources** - What data sources are required (e.g., Cost Management exports, FinOps hubs) +6. **Services used** - Azure services, Power BI license requirements +7. **Prerequisites** - What users need before using the report +8. **Setup instructions** - Step-by-step guide to configure and use the report +9. **Known limitations** - Any limitations or known issues +10. **Support** - How users can get help or report issues +11. **License** - License under which the report is shared (must be compatible with MIT) + +#### CONTRIBUTORS.md + +Your report's CONTRIBUTORS.md must include: + +1. **Technical lead** - Primary contact and maintainer +2. **Contributors** - Others who have contributed to the report +3. **Acknowledgments** - Any third-party resources or inspirations + +### Report guidelines + +1. **File format** + - Prefer Power BI Project (.pbip) format for easier source control and collaboration + - Include both .pbit (template) and optionally .pbix (with sample data) versions + - Remove any sensitive data before submitting + +2. **Documentation** + - Include screenshots of key report pages in the `images/` folder + - Provide clear, step-by-step setup instructions + - Document all parameters and configuration options + - List all data sources and connection requirements + +3. **Data sources** + - Support standard FinOps toolkit data sources when possible (Cost Management exports, FinOps hubs) + - Clearly document any custom or additional data sources needed + - Include sample queries or export configurations if needed + +4. **Naming conventions** + - Use sentence casing for report and page names (not Title Casing) + - Be descriptive but concise + - Avoid special characters in folder and file names + +5. **Quality standards** + - Test the report with real data + - Ensure the report works with the latest Power BI Desktop version + - Validate that all visuals render correctly + - Check for performance issues with larger datasets + +
+ +## ✅ Validation requirements + +Before submitting your report, please validate: + +- [ ] **Folder structure** follows the required layout +- [ ] **README.md** contains all required sections +- [ ] **CONTRIBUTORS.md** is present with maintainer information +- [ ] **Report files** are included (preferably .pbip format) +- [ ] **No sensitive data** is included in report files +- [ ] **Screenshots** are included to showcase the report +- [ ] **Setup instructions** are clear and complete +- [ ] **Report has been tested** with actual data +- [ ] **License is compatible** with MIT license +- [ ] **You commit to maintaining** the report as technical lead + +
+ +## ⚖ī¸ License and support + +### License + +All community reports must be contributed under a license compatible with the [MIT License](../../../LICENSE) that governs this repository. By contributing a report, you agree to license your contribution under the MIT License. + +### Support model + +Community reports follow a community support model similar to [Azure Quickstart Templates](https://github.com/Azure/azure-quickstart-templates): + +- **No warranty**: Reports are provided "AS IS" without warranty of any kind +- **Community maintained**: Report owners are responsible for maintenance and updates +- **Best effort support**: The FinOps toolkit team may provide guidance but does not guarantee support +- **Community reviews**: Other community members may provide feedback and suggestions +- **No SLA**: There is no service level agreement for fixes or updates + +### Getting help + +If you encounter issues with a community report: + +1. **Check the report's README** for troubleshooting guidance +2. **Contact the report maintainer** listed in CONTRIBUTORS.md +3. **Open an issue** on GitHub with the `community-report` label +4. **Ask the community** in [GitHub Discussions](https://github.com/microsoft/finops-toolkit/discussions) + +### Reporting issues + +When reporting issues with community reports: + +1. Use the report name in the issue title +2. Tag the issue with `community-report` and `Type: Bug 🐛` labels +3. @ mention the report maintainer from CONTRIBUTORS.md +4. Provide detailed reproduction steps and screenshots + +
+ +--- + +## 📚 Additional resources + +- [Official FinOps toolkit Power BI reports](../README.md) +- [Power BI report design guidelines](../README.md#-design-guidelines) +- [FinOps toolkit contribution guide](../../CONTRIBUTING.md) +- [FinOps Framework](https://www.finops.org/framework/) +- [Microsoft FinOps documentation](https://learn.microsoft.com/azure/cost-management-billing/finops/) + +
+ +_Community reports are maintained by their contributors and are not officially supported by Microsoft or the FinOps toolkit team. For supported reports, see the [official Power BI reports](../README.md)._