diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index c9b61e6da..bba273533 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,5 +1,5 @@ name: Bug report -description: Report a reproducible defect. +description: Report something that looks broken. title: "[Bug] " labels: ["bug"] body: @@ -7,48 +7,49 @@ body: id: summary attributes: label: Summary - description: What is wrong? + description: What looks wrong? validations: required: true - type: textarea id: expected attributes: - label: Expected behavior + label: What did you expect? (optional) + description: If it helps, say what you thought would happen instead. validations: required: false - type: textarea id: steps attributes: - label: Reproduction steps - description: Include exact commands or UI steps. + label: How can we reproduce it? + description: Commands, clicks, or files that help us see it. validations: required: true - type: textarea id: environment attributes: - label: Environment - description: OS, Python version, branch or commit if relevant. + label: Environment (optional) + description: OS, Python version, branch, or commit if that helps. validations: required: false - type: textarea id: evidence attributes: - label: Logs or screenshots - description: Paste relevant output or links to screenshots. + label: Logs or screenshots (optional) + description: Add anything else that helps explain it. validations: required: false - type: textarea id: related_work attributes: - label: Related work checked - description: List anything relevant you checked before opening this issue. Use issue/PR numbers like #123, or write `None found after search`. + label: Related issue, PR, or discussion (optional) + description: If you already found something relevant, link it here. validations: required: false - type: dropdown id: proposed_track attributes: label: Proposed track - description: Optional. Maintainers will assign the final track label. + description: Optional. Pick one if it helps. options: - Track: Cross-Platform - Track: OG Onboarding diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 798d06fa9..ad610d8c5 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -2,4 +2,4 @@ blank_issues_enabled: true contact_links: - name: Project support guide url: https://github.com/EAPD-DRB/MUIOGO/blob/main/SUPPORT.md - about: Read support guidance and reporting expectations. + about: See where to ask questions or report issues. diff --git a/.github/ISSUE_TEMPLATE/feature_task.yml b/.github/ISSUE_TEMPLATE/feature_task.yml index c93605cc3..6475252db 100644 --- a/.github/ISSUE_TEMPLATE/feature_task.yml +++ b/.github/ISSUE_TEMPLATE/feature_task.yml @@ -1,51 +1,51 @@ name: Feature or task -description: Propose implementation work with clear acceptance criteria. +description: Share an idea or task that could help MUIOGO. title: "[Task] " labels: ["enhancement"] body: - type: textarea id: problem attributes: - label: Problem statement - description: What problem are we solving? + label: What needs work? + description: What are you trying to improve or make easier? validations: required: true - type: textarea id: proposal attributes: - label: Proposed solution - description: Describe scope and approach. + label: Possible approach (optional) + description: If you have an idea for the direction, add it here. validations: required: false - type: textarea id: acceptance attributes: - label: Acceptance criteria - description: List objective criteria for completion. + label: What good looks like (optional) + description: If helpful, list the outcome you are aiming for. placeholder: | - - [ ] Criterion 1 - - [ ] Criterion 2 + - setup is easier to follow + - current behavior still works validations: required: false - type: textarea id: dependencies attributes: - label: Dependencies and constraints - description: Upstream or downstream constraints, blocked items, or external dependencies. + label: Anything to keep in mind? (optional) + description: Upstream impact, related decisions, blocked items, or anything else that shapes the work. validations: required: false - type: textarea id: related_work attributes: - label: Related work checked - description: List anything relevant you checked before opening this issue. Use issue/PR numbers like #123, or write `None found after search`. + label: Related issue, PR, or discussion (optional) + description: If you already found something relevant, link it here. validations: required: false - type: dropdown id: proposed_track attributes: label: Proposed track - description: Optional. Maintainers will assign the final track label. + description: Optional. Pick one if it helps. options: - Track: Cross-Platform - Track: OG Onboarding diff --git a/.github/ISSUE_TEMPLATE/question_blocker.yml b/.github/ISSUE_TEMPLATE/question_blocker.yml index e77308e98..92efcb06c 100644 --- a/.github/ISSUE_TEMPLATE/question_blocker.yml +++ b/.github/ISSUE_TEMPLATE/question_blocker.yml @@ -1,5 +1,5 @@ name: Question or blocker -description: Ask for clarification or report a blocker. +description: Ask a question or flag something that is getting in the way. title: "[Question/Blocker] " labels: ["needs-decision"] body: @@ -16,35 +16,35 @@ body: id: context attributes: label: Context - description: What are you trying to do? + description: What are you working on? validations: required: true - type: textarea id: blocking attributes: - label: What is blocked? - description: Describe the failure point or missing decision. + label: What's the question or blocker? + description: Tell us what you are unsure about or what is getting in the way. validations: required: true - type: textarea id: help attributes: - label: Requested decision or help - description: What specific answer do you need? + label: What would help? (optional) + description: If you know, say what kind of answer or decision would unblock you. validations: - required: true + required: false - type: textarea id: related_work attributes: - label: Related work checked - description: List anything relevant you checked before opening this issue. Use issue/PR numbers like #123, or write `None found after search`. + label: Related issue, PR, or discussion (optional) + description: If you already found something relevant, link it here. validations: required: false - type: dropdown id: proposed_track attributes: label: Proposed track - description: Optional. Maintainers will assign the final track label. + description: Optional. Pick one if it helps. options: - Track: Cross-Platform - Track: OG Onboarding diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 498e472c4..4bfd7f42c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ Thanks for contributing. ## Before starting -1. Read `README.md`, `docs/GSoC-2026.md`, `docs/ARCHITECTURE.md`, and `docs/DOCS_POLICY.md` +1. Read `README.md`, `docs/GSoC-2026.md`, `SUPPORT.md`, `docs/ARCHITECTURE.md`, and `docs/DOCS_POLICY.md` 2. Search existing issues and PRs before proposing implementation work 3. Create or reuse an issue before starting implementation work 4. Fill in the issue's required related-work fields so overlap is explicit diff --git a/README.md b/README.md index be96e51ee..b43b24126 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,6 @@ -# 🎓 Applications for MUIOGO Are Now Open! +# 🎓 Applications for MUIOGO Are Now Closed -Please complete the following questionnaire so we can keep track of everybody’s application in a structured way: - -🗓 **Deadline**: 16 March -📄 **Apply** [here](https://forms.gle/8Yvw2H6Q7Qw6snSN9) +For the broader project description, see [OG–CLEWS: Integrating Open-Source Economic and Environmental Models for Sustainable Development](https://opensource.unicc.org/un/unoict/mentorship-programme/google-summer-of-code/-/blob/main/README.md#ogclews-integrating-open-source-economic-and-environmental-models-for-sustainable-development). ---

@@ -89,6 +86,7 @@ One of the core goals of MUIOGO is to become platform independent so separate pl Start with: - `CONTRIBUTING.md` - `docs/GSoC-2026.md` +- `SUPPORT.md` - `docs/ARCHITECTURE.md` - `docs/DOCS_POLICY.md` diff --git a/SUPPORT.md b/SUPPORT.md index d4b67d238..3cf985405 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -2,11 +2,19 @@ ## Where to ask for help +Use GitHub Discussions for: + +- planning questions, +- general questions about the project, +- community discussion, and +- early conversation before opening implementation PRs. + Use GitHub Issues for: - bugs, - feature/task requests, -- blockers and technical questions. +- blockers, and +- actionable technical questions. Please use the relevant issue template when available. @@ -22,4 +30,3 @@ Please use the relevant issue template when available. This project uses event-driven communication. Updates are expected when work starts, when blocked, when a PR is opened, and when a milestone is complete. - diff --git a/docs/source/contributing/contributing.rst b/docs/source/contributing/contributing.rst index f4811ac89..b1a4ecb3d 100644 --- a/docs/source/contributing/contributing.rst +++ b/docs/source/contributing/contributing.rst @@ -2,111 +2,91 @@ Contributing ########################### -We warmly welcome anyone interested in MUIO and the broader OSeMOSYS ecosystem! Whether you have ideas, suggestions, bug reports, or would like to contribute improvements, your input is highly valued. +MUIOGO is an open-source project, and contributions are welcome. -How You Can Contribute ---------------------------- - -🧠 `Code Contributions`_ - -Help us enhance MUIO by adding new functionalities, fixing bugs, or optimizing model performance. +The most useful contributions are clear, scoped, and grounded in the current +direction of the repository. Before proposing implementation work, take time to +understand what the project is trying to do, what already exists, and how your +proposal fits the current priorities. -📚 `Documentation`_ - -Support the community by expanding or refining the documentation—add new sections, correct errors, or improve clarity for new users. +Getting Started +--------------------------- -📂 `Examples and Use Cases`_ +Start with the repository documentation: -Share your modelling examples or country applications. These can be valuable learning tools for others in the community. +* ``README.md`` +* ``CONTRIBUTING.md`` +* ``SUPPORT.md`` +* ``docs/ARCHITECTURE.md`` +* ``docs/DOCS_POLICY.md`` +These documents are the source of truth for the contributor workflow. Code Contributions ------------------- -Want to suggest a fix or add a feature? Here's a quick and easy workflow: - -1. Fork the repository: Click the “Fork” button on the `MUIO GitHub page `_ +MUIOGO uses an issue-first, discussion-before-PR workflow for most +implementation work. -2. Clone your fork: Copy the link to your fork and run: +Before writing code: -.. code:: bash +1. Search existing issues, pull requests, and discussions. +2. Create or reuse an issue before starting implementation work. +3. Describe the current problem, relevant related work, and why the issue is + still needed. +4. Confirm the scope before opening a large implementation PR. +5. Create a feature branch from ``main`` for the implementation. - git clone https://github.com//MUIO.git - -3. Make your changes: Create a new branch and make your edits or improvements in the code. +Why this matters: -4. Test your changes: If there are tests, run them locally. If not, just make sure your edits work as expected. +* it reduces duplicate or overlapping work +* it helps maintainers keep review effort focused on current priorities +* it makes it easier to discuss tradeoffs before code is written -5. Push and open a pull request: Push your branch to your fork and go to GitHub to open a pull request. +MUIOGO is downstream from ``OSeMOSYS/MUIO``. Contributors should avoid creating +unnecessary divergence from upstream when a narrower or more compatible change +would do the job. -Documentation +Documentation Contributions ------------------- -We aim to keep the MUIO documentation clear, helpful, and up to date. If you notice any gaps, outdated content, or unclear explanations, your help in improving it is greatly appreciated. - -How to Contribute to the Docs: - -1. Find something to improve - Spotted a typo, unclear sentence, or missing sections. - -2. Edit directly on GitHub - - - On any documentation page, click the book icon (📖) at the bottom-left corner. - - Then click “Edit on GitHub” – this will take you to the exact source file. - -3. Make your changes - Use GitHub’s built-in editor to edit the file directly. +Documentation improvements are welcome, including: -4. Propose your edit - Once done, commit the changes and open a pull request. We’ll review and merge it! +* clarifying setup steps +* fixing outdated or misleading instructions +* improving architecture or workflow explanations +* adding missing validation or troubleshooting details +Any setup, workflow, or architecture change should update the relevant +documentation in the same pull request. Examples and Use Cases ------------------- -Have you built a useful energy model using MUIO? We'd love to include it as an example to help others learn and build faster. Here's how to contribute an example to the documentation: +Examples, demo improvements, and real-world use cases can be helpful when they +make the project easier to understand or test. -✅ What Makes a Good Example? -^^^^^^^^^^^^^^^^^^^^^^ +If you want to contribute an example: -We welcome examples that: +1. Explain what the example demonstrates. +2. Keep it small enough to be practical for review and reuse. +3. Include a short README or description covering the purpose, assumptions, and + any data-source constraints. +4. Open or link an issue first if the example changes tracked project scope, + demo assets, or contributor workflow. -* Use MUIO in real or hypothetical case studies (e.g. countries, regions, sectors). - -* Demonstrate specific features (e.g. multi-regional modelling, transport sector, emissions). - -* Include complete data files, clear naming, and a brief description. - -* Are small enough to run quickly (or include a simplified version). - -🚀 How to Contribute an Example -^^^^^^^^^^^^^^^^^^^^^^ - -1. Prepare your files - - - Organize your example in a folder under ``examples/`` (e.g. ``examples/CountryName/``). - - Include: - - - Model input file (.zip) - - A ``README.md`` describing the model purpose, data source, and assumptions - - *(Optional)* Output plots or summary results - -2. Fork and clone the MUIO repository. - -3. Add your folder under ``/examples``. - If it’s large, consider linking to an external repository or storage (e.g. Zenodo, Figshare). - -4. Add a reference in the documentation - - - Edit the examples section in the documentation (``docs/source/examples.rst``). - - Add a short entry linking to your example folder or external repo. +Communication +------------------- -5. Create a pull request - Submit your changes with a short description of your example. +Good communication is part of the contribution. -📝 Licensing and Attribution -^^^^^^^^^^^^^^^^^^^^^^ +Strong contributions usually include: -* Please include a note in your README.md indicating data sources and your preferred citation (if any). +* a concrete problem statement +* a scoped proposal +* links to related work already reviewed +* clear validation steps +* direct explanations of tradeoffs or upstream-compatibility impact -* Make sure you have the right to share the data and code you include. +Questions are welcome. It is especially helpful when questions include enough +context to make them easy to answer and act on. diff --git a/docs/source/contributing/support.rst b/docs/source/contributing/support.rst index 94a4e2c5c..72a948adb 100644 --- a/docs/source/contributing/support.rst +++ b/docs/source/contributing/support.rst @@ -2,17 +2,46 @@ Support and Troubleshooting ########################### -Need help using MUIO or found a bug? There are several ways to reach out and contribute to the improvement of the tool. +Need help using MUIOGO, planning work, or reporting a problem? Use the +repository channels based on the kind of help you need. -💬 Community Support -++++++++++++++++++++ +Community and Planning Questions ++++++++++++++++++++++++++++++++++ -To connect with other MUIO and OSeMOSYS users, ask questions, share updates, or collaborate on projects, you can: -• Join the OSeMOSYS Community via the Energy Modelling Community on `Linkedin `_ -• Participate in discussions on the OSeMOSYS Discourse Forum [Link to be updated soon] +Use `GitHub Discussions `_ for: -🐞 Report Bugs or Suggest Features -++++++++++++++++++++++++++++++++++ +* planning questions +* general questions about the project +* community conversation +* early discussion before opening implementation pull requests -Found a bug? Have an idea for a new feature? Please open an issue on the `GitHub Issue Tracker `_ -Be sure to describe the problem clearly and include steps to reproduce it, if possible. +Discussions are the right place to ask questions, compare approaches, and sort +out scope before work turns into a PR. + +Bugs, Blockers, and Actionable Work ++++++++++++++++++++++++++++++++++ + +Use the `GitHub Issue Tracker `_ for: + +* reproducible bugs +* scoped feature or task proposals +* blockers that need a concrete decision +* actionable follow-up work + +Please use the relevant issue template and include enough detail to make the +problem easy to understand and triage. + +What To Include ++++++++++++++++++++++++++++++++++ + +When reporting a bug or blocker, include: + +* a clear problem statement +* expected behavior +* reproduction steps +* environment details such as OS, Python version, and branch or commit when + relevant +* logs or screenshots when helpful + +If the issue depends on prior work, list the related issues, pull requests, or +discussions you already checked.