From 5bea7461fc1120016866a6c36f549ff804df21b6 Mon Sep 17 00:00:00 2001 From: tdaly61 Date: Sat, 18 Jul 2026 11:07:49 +0930 Subject: [PATCH 1/3] chore: refresh standard docs (CONTRIBUTING/CODE_OF_CONDUCT/README) Removes the leftover generic ActionHub-KMP boilerplate description from README.md, adds CODE_OF_CONDUCT.md, and refreshes CONTRIBUTING.md to the current openMF template. --- CODE_OF_CONDUCT.md | 4 + CONTRIBUTING.md | 318 +++++++++++++++++++++++++++++++++------------ README.md | 14 +- 3 files changed, 253 insertions(+), 83 deletions(-) create mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..1688499 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,4 @@ +# Code of Conduct + +- Always follow the Mifos Initiative [code of conduct](https://mifos.org/resources/community/code-of-conduct/) + \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6b6f42f..40e2fd8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,149 +1,303 @@ # Contributing to paymenthub-ee-core -Thank you for your interest in contributing to the paymenthub-ee-core repository! Your contributions are important and will help to improve the project for everyone. Before you begin, please consider the guidelines below. +Thank you for your interest in contributing to paymenthub-ee-core! We welcome contributions from the community to help improve financial inclusion solutions globally. -## Branches +To ensure a smooth collaboration process and maintain code quality, we enforce a strict contribution workflow. Please read this guide carefully before submitting any code. -* Main - contains released versions of the paymenthub-ee-core product. This should be considered the stable branch. -* Dev - Where all contributions should be raised as PRs, this should be considered as pre-release code -* ... - Individual branches used by contributors for pre-staging or testing but note our reserved branch names. +## Quick Links -## Reserved Branch Names and Tags +- View the [README](./README.md) to get your development environment up and running. +- Sign the [Contribution License Agreement](http://mifos.org/about-us/financial-legal/mifos-contributor-agreement/). +- Always follow the [code of conduct](https://mifos.org/resources/community/code-of-conduct/) - this is important to us. +- Learn more at our [getting started guide](https://mifosforge.jira.com/wiki/spaces/RES/pages/464322561/New+Contributor+Getting+Started+Guide). +- Have a look at our [Wiki](https://github.com/openMF/paymenthub-ee-core/wiki). +- Sign up to Mifos Slack -The following branch names and tags (and derivatives and extensions e.g., releasev1.0) are reserved for use by Mifos Organisation. Any branches created by non-admins with these names will be deleted without notice: +--- -- main -- master -- dev -- development -- sec -- security -- mifos -- release -- rel -- rc -- staging -- prod -- production -- gsoc -- test -- testing +## The Golden Rule: Discuss First -## Releases +> **Do not open a Pull Request without prior discussion.** -Please always contribute to **Dev**. We then compile accepted PRs from Dev into releases within the community the timing of these releases is. +We avoid "surprise" contributions. Before writing code, you must validate your idea with the community to ensure it aligns with the roadmap and isn't already in progress. -## Getting Started +--- -- View the [README](README.md) to get your development environment up and running. -- Sign the [Contribution License Agreement](https://mifos.org/about-us/financial-legal/mifos-contributor-agreement/). -- Always follow the [code of conduct](https://mifos.org/resources/community/code-of-conduct/) - this is important to us. We are proud to be open, tolerant and providing a positive environment. -- Introduce yourself or ask a question on the [Mifos Slack](https://mifos.slack.com/ssb/redirect). -- Find a [Jira](https://mifosforge.jira.com/jira/software/c/projects) ticket to work on. -- If its is already assigned you are not allowed to take it. Instead you must ask the person assigned and they may choose to re-assign it to you. -- If its not assigned you can assign it to yourself. Make sure you keep the status of the ticket up to date and include in comments your progress e.g. screenshots. -- If you need too you can raise a Jira ticket on our board for a new feature or enhancement that you want to work on that doesnt have an existing ticket. However its good community spirit to discuss what you are planning in our slack first. It may also save you wasting time. -- Make sure you have [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed on your machine. -- Fork the repository and clone it locally. +## Step 1: Discuss on Slack -git clone --branch dev https://github.com/openMF/paymenthub-ee-core.git +Before you start coding (especially for new features or refactoring), you must signal your intent. +1. **Join the Community:** [Mifos Slack](https://mifos.slack.com) +2. **Find the Channel:** Navigate to the channel for this repo/project +3. **Post Your Proposal:** + - **Features:** Explain what you want to build and why. + - **Bugs:** Briefly explain the issue and provide screenshots if applicable. +4. **Wait for Approval:** Do not proceed until a maintainer or community member acknowledges the task is valid and free for you to take. -- Create a new branch for your contributions -git checkout -b feature-branch-name +--- +## Step 2: Jira Issue Tracking -## Making Changes +All development work is tracked in Jira to manage the release backlog and ensure transparency. -- Before making changes, ensure that you're working on the latest version of the `dev` branch +- **System:** [Mifos Jira](https://mifosforge.jira.com) +- **Project:** see this repo's README/Wiki for the Jira project key and board. -git pull origin dev +### Workflow +1. **Search:** Check the project's Jira board to ensure the ticket doesn't already exist. +2. **Create:** If unique, create a new ticket in the project. + - **Summary:** `[Component] Concise description` (e.g., `[Client] Fix submit button alignment`) + - **Description:** Steps to reproduce, expected result, actual result, and environment details. +3. **Assign:** + - Assign the ticket to yourself if you have permissions. + - If you lack permissions, comment "I am working on this" on the ticket and ask a maintainer to assign it to you. +4. **Manage Status:** + - **To Do:** Task is open. + - **In Progress:** Move here immediately when you begin coding. + - **In Review:** Move here when you post the PR link in the comments. + - **Done:** Do not move here. Maintainers will move the ticket to Done after the PR is merged. -## Committing Changes +--- -- Stage your changes: +## Step 3: Branching Strategy -git add file-name(s) +We follow a strict branching model to keep our history clean. -- Commit your changes with a descriptive message: +- **Upstream Branch:** Always branch from `dev`. Never branch from `master` or `main`. +- **Naming Convention:** Your branch name must include the Jira Ticket ID. + - **Format:** `-` + - **Example:** `git checkout -b PROJ-123-fix-login-button` -git commit -m "Add feature" +### Reserved Branch Names -- Push your changes to your forked repository: +The following branch names and tags (and their derivatives/extensions) are reserved for use by Mifos Organisation. Any branches created by non-admins with these names will be deleted without notice: -git push origin feature-branch-name +- `main` +- `master` +- `dev` +- `development` +- `sec` / `security` +- `mifos` +- `release` / `rel` / `rc` +- `staging` +- `prod` / `production` +- `gsoc` +--- -## Submitting a Pull Request - -- Follow the steps outlined in [GitHub's documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) -- The following items are mandatory for all Pull Requests. -- (1) Contributor Licence agreement has been signed -- (2) PR title includes the JIRA ticket reference to allow for tracking -- (3) PR Description explains what you have done, it should include testing and scripts -- (4) You declaire if you have used AI and where. Use of AI is fine but you are expected to have reviewed the output made necessary changes and licence checks and removed any unnecessary AI changes (e.g. removed AI adding of random templates and styles) - -## Commit Hygiene (Squash) +## Step 4: Commit Hygiene (Squash) We maintain a linear, meaningful git history. - **One Feature = One PR:** Do not combine unrelated fixes. - **Squash Requirement:** If your PR contains more than 2 commits, you must squash them. - ❌ **Bad History:** `init`, `wip`, `typo`, `fix`, `fix again` - - ✅ **Good History:** `TICKET-123: Implement data load functionality` + - ✅ **Good History:** `PROJ-123: Implement client search functionality` -**How to Squash (Step-by-Step Example):** +**How to Squash (Example for last 2 commits):** -1. **Start Interactive Rebase:** Run the following command (replace `2` with the number of commits you want to combine): +1. **Start Interactive Rebase:** ```bash git rebase -i HEAD~2 ``` -2. **Edit the Rebase File:** An editor will open listing your recent commits. It will look like this: +2. **Edit the Rebase File:** + An editor will open listing the last two commits. It will look similar to this: ```text pick a1b2c3d Message of the older commit pick e4f5g6h Message of the newer commit ``` -3. **Squash the Commits:** Change `pick` to `squash` (or `s`) for all commits except the first one: +3. **Squash the Commits:** + Change the second `pick` to `squash` or `s`: ```text pick a1b2c3d Message of the older commit s e4f5g6h Message of the newer commit ``` -4. **Save and Close:** Save the file and close the editor. +4. **Save and Close:** + Save the file and close the editor. -5. **Finalize Message:** A new editor window will appear. Combine or edit the commit messages into a single, meaningful title (e.g., `TICKET-123: Feature description`). Save and close. +5. **Finalize Message:** + A new editor window will appear allowing you to combine or edit the commit messages for the new, single commit. -6. **Force Push:** Send the changes to your remote repository. +6. **Push the Changes:** + Push the changes to your remote repository: ```bash - git push origin branch-name --force-with-lease + git push --force-with-lease ``` +--- + +## Step 5: Pull Request Checklist + +When you are ready to submit your PR: + +- [ ] **Target:** The `dev` branch. +- [ ] **Title:** Includes the Jira Key (e.g., `PROJ-123: Fix login button`). +- [ ] **Description:** Includes a link to the Jira ticket. +- [ ] **Context:** Includes a link to the Slack discussion or summary of approval. +- [ ] **Quality:** Passes this project's linting/formatting/test tooling and CI checks. +- [ ] **AI use:** Declare if you used AI and where. Use of AI is fine but you are expected to have reviewed the output, made necessary changes, and removed any unnecessary AI-added content (e.g. random templates/styles the task didn't call for). + +--- + +## Git and GitHub Workflow + +### Best Practices to send Pull Requests + +- Fork the [project](https://github.com/openMF/paymenthub-ee-core) on GitHub +- Clone the project locally into your system. + +```bash +git clone https://github.com/your-username/paymenthub-ee-core.git +``` + +- We use the `main` branch for releases, hotfixes and special purposes. All regular work on releases flows into the `dev` branch. + +```bash +git checkout dev +``` + +- Create a new branch with a meaningful name before adding and committing your changes. + +```bash +git checkout -b branch-name +``` + +- Add the files you changed. (Better don't use `git add .`) + +```bash +git add file-name +``` + +- Follow the style conventions for a meaningful commit message. + +```bash +git commit +``` + +- If you forgot to add some changes, you can edit your previous commit message. + +```bash +git commit --amend +``` + +- Squash multiple commits to a single commit. (Example: squash last two commits done on this branch into one.) + +```bash +git rebase --interactive HEAD~2 +``` + +- Push this branch to your remote repository on GitHub. + +```bash +git push --set-upstream origin branch-name +``` + +- If any of the squashed commits have already been pushed to your remote repository, you need to do a force push. + + ```bash + git push origin branch-name --force-with-lease + ``` + +- Follow the Pull request template and submit a pull request with a motive for your change and the method you used to achieve it to be merged with the `dev` branch. +- If possible, please submit the pull request along with tests. +- During review, if changes are requested, rebase your branch and squash commits again. Once you push, the pull request updates automatically. + +### Configuring Remotes + +When a repository is cloned, it has a default remote called `origin` that points to your fork on GitHub, not the original repository it was forked from. To keep track of the original repository, you can add another remote called `upstream`. + +1. Set the `upstream`. + +```bash +git remote add upstream https://github.com/openMF/paymenthub-ee-core.git +``` + +2. Use `git remote -v` to check the status. The output must be something like this: + +```bash + > origin https://github.com/your-username/paymenthub-ee-core.git (fetch) + > origin https://github.com/your-username/paymenthub-ee-core.git (push) + > upstream https://github.com/openMF/paymenthub-ee-core.git (fetch) + > upstream https://github.com/openMF/paymenthub-ee-core.git (push) +``` + +3. To update your local copy with remote changes, run the following: (This will give you an exact copy of the current remote. You should not have any local changes on your dev branch, if you do, use rebase instead.) + +```bash +git fetch upstream +git checkout dev +git merge upstream/dev +``` + +4. Push these merged changes to the `dev` branch on your fork. (Pull upstream changes regularly to keep your fork up to date, or use the "Sync fork" button at the top of your fork's GitHub page, then run `git pull`.) + +```bash +git push origin dev +``` + +5. Switch to the branch you are using for some piece of work. + +```bash +git checkout branch-name +``` + +6. Rebase your branch, which means, take in all latest changes and replay your work in the branch on top of this - this produces cleaner versions/history. + +```bash +git rebase dev +``` + +7. Push the final changes when you're ready. + +```bash +git push origin branch-name +``` + +### After your Pull Request is merged + +After your pull request is merged, you can safely delete your branch and pull the changes from the dev (upstream) repository. + +1. Delete the remote branch on GitHub. + +```bash +git push origin --delete branch-name +``` + +2. Checkout the dev branch. + +```bash +git checkout dev +``` + +3. Delete the local branch. + +```bash +git branch -D branch-name +``` -## Code Review +4. Update your dev branch with the latest upstream version. -- After submitting your PR, our team will review your changes. -- Address any feedback or requested changes promptly. -- Once approved, your PR will be merged into the `dev` branch. -- Every release we will take the release from the 'dev' branch to the 'main' branch +```bash +git pull upstream dev +``` -## After your PR is merged +### Skipping a CI Build -After your PR has been reviewed any feedback taken on board and merged there are a few things to keep things tidy we like you to do. -- Delete your branch unless you think it will be needed again -- update Jira status to `DONE` if its the last PR you need to raise to address a ticket. **Do not do this if you will need to raise another PR to fully address the scope or if its still in PR review.** +If running a build is not required for a particular commit (in some cases like an update to README.md), add [ci skip] or [skip ci] to the git commit message. Commits that have [ci skip] or [skip ci] anywhere in the commit messages are ignored by CI. -## Reporting Issues +--- -If you find any bugs or have recommendations for improvements, please feel free to raise a ticket on our Jira board with a detailed explanation of issue ideally including steps to reproduce and screenshots/video. +## Getting Help -## Contact +If you get stuck, please reach out on [Mifos Slack](https://mifos.slack.com). We are happy to help you navigate the codebase or troubleshoot environment issues! -- For further assistance or questions regarding contributions, feel free to join our Slack channel [here](https://mifos.slack.com/ssb/redirect). If you need an invite you can use this [link](https://join.slack.com/t/mifos/shared_invite/zt-3m6x47dgj-iX0Oqv8KS0VGgouNnuJrAg) +--- -Thank you again for your interest in [paymenthub-ee-core](https://github.com/openMF/paymenthub-ee-core)! We look forward to your contributions. +**_Thank you for contributing!_** diff --git a/README.md b/README.md index 8346ebd..c7cc6c8 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,14 @@ # paymenthub-ee-core -MifosX ActionHub KMP publishing (kmp) + +_Placeholder — replace this line with a one-sentence description of what paymenthub-ee-core does._ + +[![License](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](LICENSE) + +## Branches + +- `dev` is the active development branch — all PRs should target `dev`. +- `main` holds released versions. + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md). From 50b121eb19c7c6beb58d5caf11f91f1f336a98e1 Mon Sep 17 00:00:00 2001 From: tdaly61 Date: Sat, 18 Jul 2026 11:19:18 +0930 Subject: [PATCH 2/3] chore: source CONTRIBUTING.md from mifos-gazelle instead --- CONTRIBUTING.md | 317 +++++++++++++----------------------------------- 1 file changed, 81 insertions(+), 236 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 40e2fd8..0dabfed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,303 +1,148 @@ # Contributing to paymenthub-ee-core + Thank you for your interest in contributing to the paymenthub-ee-core repository! Your contributions are important and will help to improve the project for everyone. Before you begin, please consider the guidelines below. -Thank you for your interest in contributing to paymenthub-ee-core! We welcome contributions from the community to help improve financial inclusion solutions globally. +## Branches -To ensure a smooth collaboration process and maintain code quality, we enforce a strict contribution workflow. Please read this guide carefully before submitting any code. +* Main - contains released versions of the paymenthub-ee-core product. This should be considered the stable branch. +* Dev - Where all contributions should be raised as PRs, this should be considered as pre-release code +* ... - Individual branches used by contributors for pre-staging or testing but note our reserved branch names. -## Quick Links +## Reserved Branch Names and Tags -- View the [README](./README.md) to get your development environment up and running. -- Sign the [Contribution License Agreement](http://mifos.org/about-us/financial-legal/mifos-contributor-agreement/). -- Always follow the [code of conduct](https://mifos.org/resources/community/code-of-conduct/) - this is important to us. -- Learn more at our [getting started guide](https://mifosforge.jira.com/wiki/spaces/RES/pages/464322561/New+Contributor+Getting+Started+Guide). -- Have a look at our [Wiki](https://github.com/openMF/paymenthub-ee-core/wiki). -- Sign up to Mifos Slack +The following branch names and tags (and derivatives and extensions e.g., releasev1.0) are reserved for use by Mifos Organisation. Any branches created by non-admins with these names will be deleted without notice: ---- +- main +- master +- dev +- development +- sec +- security +- mifos +- release +- rel +- rc +- staging +- prod +- production +- gsoc +- test +- testing -## The Golden Rule: Discuss First +## Releases -> **Do not open a Pull Request without prior discussion.** +Please always contribute to **Dev**. We then compile accepted PRs from Dev into releases within the community the timing of these releases is. -We avoid "surprise" contributions. Before writing code, you must validate your idea with the community to ensure it aligns with the roadmap and isn't already in progress. +## Getting Started ---- +- View the [README](README.MD) to get your development environment up and running. +- Sign the [Contribution License Agreement](https://mifos.org/about-us/financial-legal/mifos-contributor-agreement/). +- Always follow the [code of conduct](https://mifos.org/resources/community/code-of-conduct/) - this is important to us. We are proud to be open, tolerant and providing a positive environment. +- Introduce yourself or ask a question on the [Mifos Slack](https://mifos.slack.com/ssb/redirect). +- Find a [Jira](https://mifosforge.jira.com/jira/software/c/projects/GAZ/issues?jql=project%20%3D%20%22GAZ%22%20ORDER%20BY%20created%20DESC) ticket to work on. +- If its is already assigned you are not allowed to take it. Instead you must ask the person assigned and they may choose to re-assign it to you. +- If its not assigned you can assign it to yourself. Make sure you keep the status of the ticket up to date and include in comments your progress e.g. screenshots. +- If you need too you can raise a [Jira] ticket on our board for a new feature or enhancement that you want to work on that doesnt have an existing ticket. However its good community spirit to discuss what you are planning in our Slack first. It may also save you wasting time. +- Make sure you have [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed on your machine. +- Fork the repository and clone it locally. -## Step 1: Discuss on Slack +git clone --branch dev https://github.com/openMF/paymenthub-ee-core.git -Before you start coding (especially for new features or refactoring), you must signal your intent. -1. **Join the Community:** [Mifos Slack](https://mifos.slack.com) -2. **Find the Channel:** Navigate to the channel for this repo/project -3. **Post Your Proposal:** - - **Features:** Explain what you want to build and why. - - **Bugs:** Briefly explain the issue and provide screenshots if applicable. -4. **Wait for Approval:** Do not proceed until a maintainer or community member acknowledges the task is valid and free for you to take. +- Create a new branch for your contributions +git checkout -b feature-branch-name ---- -## Step 2: Jira Issue Tracking +## Making Changes -All development work is tracked in Jira to manage the release backlog and ensure transparency. +- Before making changes, ensure that you're working on the latest version of the `dev` branch -- **System:** [Mifos Jira](https://mifosforge.jira.com) -- **Project:** see this repo's README/Wiki for the Jira project key and board. +git pull origin dev -### Workflow -1. **Search:** Check the project's Jira board to ensure the ticket doesn't already exist. -2. **Create:** If unique, create a new ticket in the project. - - **Summary:** `[Component] Concise description` (e.g., `[Client] Fix submit button alignment`) - - **Description:** Steps to reproduce, expected result, actual result, and environment details. -3. **Assign:** - - Assign the ticket to yourself if you have permissions. - - If you lack permissions, comment "I am working on this" on the ticket and ask a maintainer to assign it to you. -4. **Manage Status:** - - **To Do:** Task is open. - - **In Progress:** Move here immediately when you begin coding. - - **In Review:** Move here when you post the PR link in the comments. - - **Done:** Do not move here. Maintainers will move the ticket to Done after the PR is merged. +## Committing Changes ---- +- Stage your changes: -## Step 3: Branching Strategy +git add file-name(s) -We follow a strict branching model to keep our history clean. +- Commit your changes with a descriptive message: -- **Upstream Branch:** Always branch from `dev`. Never branch from `master` or `main`. -- **Naming Convention:** Your branch name must include the Jira Ticket ID. - - **Format:** `-` - - **Example:** `git checkout -b PROJ-123-fix-login-button` +git commit -m "Add feature" -### Reserved Branch Names +- Push your changes to your forked repository: -The following branch names and tags (and their derivatives/extensions) are reserved for use by Mifos Organisation. Any branches created by non-admins with these names will be deleted without notice: +git push origin feature-branch-name -- `main` -- `master` -- `dev` -- `development` -- `sec` / `security` -- `mifos` -- `release` / `rel` / `rc` -- `staging` -- `prod` / `production` -- `gsoc` ---- +## Submitting a Pull Request -## Step 4: Commit Hygiene (Squash) +- Follow the steps outlined in [GitHub's documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) +- The following items are mandatory for all Pull Requests. +- (1) Contributor Licence agreement has been signed +- (2) PR title includes the JIRA ticket reference to allow for tracking +- (3) PR Description explains what you have done, it should include testing and scripts +- (4) You declaire if you have used AI and where. Use of AI is fine but you are expected to have reviewed the output made necessary changes and licence checks and removed any unnecessary AI changes (e.g. removed AI adding of random templates and styles) + +## Commit Hygiene (Squash) We maintain a linear, meaningful git history. - **One Feature = One PR:** Do not combine unrelated fixes. - **Squash Requirement:** If your PR contains more than 2 commits, you must squash them. - ❌ **Bad History:** `init`, `wip`, `typo`, `fix`, `fix again` - - ✅ **Good History:** `PROJ-123: Implement client search functionality` + - ✅ **Good History:** `GAZ-123: Implement data load functionality` -**How to Squash (Example for last 2 commits):** +**How to Squash (Step-by-Step Example):** -1. **Start Interactive Rebase:** +1. **Start Interactive Rebase:** Run the following command (replace `2` with the number of commits you want to combine): ```bash git rebase -i HEAD~2 ``` -2. **Edit the Rebase File:** - An editor will open listing the last two commits. It will look similar to this: +2. **Edit the Rebase File:** An editor will open listing your recent commits. It will look like this: ```text pick a1b2c3d Message of the older commit pick e4f5g6h Message of the newer commit ``` -3. **Squash the Commits:** - Change the second `pick` to `squash` or `s`: +3. **Squash the Commits:** Change `pick` to `squash` (or `s`) for all commits except the first one: ```text pick a1b2c3d Message of the older commit s e4f5g6h Message of the newer commit ``` -4. **Save and Close:** - Save the file and close the editor. +4. **Save and Close:** Save the file and close the editor. -5. **Finalize Message:** - A new editor window will appear allowing you to combine or edit the commit messages for the new, single commit. +5. **Finalize Message:** A new editor window will appear. Combine or edit the commit messages into a single, meaningful title (e.g., `GAZ-123: Feature description`). Save and close. -6. **Push the Changes:** - Push the changes to your remote repository: +6. **Force Push:** Send the changes to your remote repository. ```bash - git push --force-with-lease + git push origin branch-name --force-with-lease ``` ---- - -## Step 5: Pull Request Checklist - -When you are ready to submit your PR: - -- [ ] **Target:** The `dev` branch. -- [ ] **Title:** Includes the Jira Key (e.g., `PROJ-123: Fix login button`). -- [ ] **Description:** Includes a link to the Jira ticket. -- [ ] **Context:** Includes a link to the Slack discussion or summary of approval. -- [ ] **Quality:** Passes this project's linting/formatting/test tooling and CI checks. -- [ ] **AI use:** Declare if you used AI and where. Use of AI is fine but you are expected to have reviewed the output, made necessary changes, and removed any unnecessary AI-added content (e.g. random templates/styles the task didn't call for). - ---- - -## Git and GitHub Workflow - -### Best Practices to send Pull Requests - -- Fork the [project](https://github.com/openMF/paymenthub-ee-core) on GitHub -- Clone the project locally into your system. - -```bash -git clone https://github.com/your-username/paymenthub-ee-core.git -``` - -- We use the `main` branch for releases, hotfixes and special purposes. All regular work on releases flows into the `dev` branch. - -```bash -git checkout dev -``` - -- Create a new branch with a meaningful name before adding and committing your changes. - -```bash -git checkout -b branch-name -``` - -- Add the files you changed. (Better don't use `git add .`) - -```bash -git add file-name -``` - -- Follow the style conventions for a meaningful commit message. - -```bash -git commit -``` - -- If you forgot to add some changes, you can edit your previous commit message. - -```bash -git commit --amend -``` - -- Squash multiple commits to a single commit. (Example: squash last two commits done on this branch into one.) - -```bash -git rebase --interactive HEAD~2 -``` - -- Push this branch to your remote repository on GitHub. - -```bash -git push --set-upstream origin branch-name -``` - -- If any of the squashed commits have already been pushed to your remote repository, you need to do a force push. - - ```bash - git push origin branch-name --force-with-lease - ``` - -- Follow the Pull request template and submit a pull request with a motive for your change and the method you used to achieve it to be merged with the `dev` branch. -- If possible, please submit the pull request along with tests. -- During review, if changes are requested, rebase your branch and squash commits again. Once you push, the pull request updates automatically. - -### Configuring Remotes - -When a repository is cloned, it has a default remote called `origin` that points to your fork on GitHub, not the original repository it was forked from. To keep track of the original repository, you can add another remote called `upstream`. - -1. Set the `upstream`. - -```bash -git remote add upstream https://github.com/openMF/paymenthub-ee-core.git -``` - -2. Use `git remote -v` to check the status. The output must be something like this: - -```bash - > origin https://github.com/your-username/paymenthub-ee-core.git (fetch) - > origin https://github.com/your-username/paymenthub-ee-core.git (push) - > upstream https://github.com/openMF/paymenthub-ee-core.git (fetch) - > upstream https://github.com/openMF/paymenthub-ee-core.git (push) -``` - -3. To update your local copy with remote changes, run the following: (This will give you an exact copy of the current remote. You should not have any local changes on your dev branch, if you do, use rebase instead.) - -```bash -git fetch upstream -git checkout dev -git merge upstream/dev -``` - -4. Push these merged changes to the `dev` branch on your fork. (Pull upstream changes regularly to keep your fork up to date, or use the "Sync fork" button at the top of your fork's GitHub page, then run `git pull`.) - -```bash -git push origin dev -``` - -5. Switch to the branch you are using for some piece of work. - -```bash -git checkout branch-name -``` - -6. Rebase your branch, which means, take in all latest changes and replay your work in the branch on top of this - this produces cleaner versions/history. - -```bash -git rebase dev -``` - -7. Push the final changes when you're ready. - -```bash -git push origin branch-name -``` - -### After your Pull Request is merged - -After your pull request is merged, you can safely delete your branch and pull the changes from the dev (upstream) repository. - -1. Delete the remote branch on GitHub. - -```bash -git push origin --delete branch-name -``` - -2. Checkout the dev branch. - -```bash -git checkout dev -``` - -3. Delete the local branch. - -```bash -git branch -D branch-name -``` -4. Update your dev branch with the latest upstream version. +## Code Review -```bash -git pull upstream dev -``` +- After submitting your PR, our team will review your changes. +- Address any feedback or requested changes promptly. +- Once approved, your PR will be merged into the `dev` branch. +- Every release we will take the release from the 'dev' branch to the 'main' branch -### Skipping a CI Build +## After your PR is merged -If running a build is not required for a particular commit (in some cases like an update to README.md), add [ci skip] or [skip ci] to the git commit message. Commits that have [ci skip] or [skip ci] anywhere in the commit messages are ignored by CI. +After your PR has been reviewed any feedback taken on board and merged there are a few things to keep things tidy we like you to do. +- Delete your branch unless you think it will be needed again +- update Jira status to `DONE` if its the last PR you need to raise to address a ticket. **Do not do this if you will need to raise another PR to fully address the scope or if its still in PR review.** ---- +## Reporting Issues -## Getting Help +If you find any bugs or have recommendations for improvements, please feel free to [raise a bug here](https://mifosforge.jira.com/jira/software/c/projects/GAZ/issues?jql=project%20%3D%20%22GAZ%22%20ORDER%20BY%20created%20DESC) with a detailed explanation of issue ideally including steps to reproduce and screenshots/video. -If you get stuck, please reach out on [Mifos Slack](https://mifos.slack.com). We are happy to help you navigate the codebase or troubleshoot environment issues! +## Contact ---- +- For further assistance or questions regarding contributions, feel free to join our Slack channel [here](https://mifos.slack.com/ssb/redirect). If you need an invite you can use this [link](https://join.slack.com/t/mifos/shared_invite/zt-3m6x47dgj-iX0Oqv8KS0VGgouNnuJrAg) -**_Thank you for contributing!_** +Thank you again for your interest in [paymenthub-ee-core](https://github.com/openMF/paymenthub-ee-core)! We look forward to your contributions. From 88a52bbb77f896b904b99a94723a5758dd6de279 Mon Sep 17 00:00:00 2001 From: tdaly61 Date: Sat, 18 Jul 2026 11:36:35 +0930 Subject: [PATCH 3/3] chore: correct CONTRIBUTING.md source to mifos-tools github-policies/contributing.md --- CONTRIBUTING.md | 356 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 276 insertions(+), 80 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0dabfed..c747419 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,148 +1,344 @@ # Contributing to paymenthub-ee-core - Thank you for your interest in contributing to the paymenthub-ee-core repository! Your contributions are important and will help to improve the project for everyone. Before you begin, please consider the guidelines below. -## Branches +Thank you for your interest in contributing to the paymenthub-ee-core! We welcome contributions from the community to help improve financial inclusion solutions globally. -* Main - contains released versions of the paymenthub-ee-core product. This should be considered the stable branch. -* Dev - Where all contributions should be raised as PRs, this should be considered as pre-release code -* ... - Individual branches used by contributors for pre-staging or testing but note our reserved branch names. +To ensure a smooth collaboration process and maintain code quality, we enforce a strict **7-Step Contribution Workflow**. Please read this guide carefully before submitting any code. -## Reserved Branch Names and Tags +## Quick Links -The following branch names and tags (and derivatives and extensions e.g., releasev1.0) are reserved for use by Mifos Organisation. Any branches created by non-admins with these names will be deleted without notice: +- View the [README](./README.md) to get your development environment up and running. +- Sign the [Contribution License Agreement](http://mifos.org/about-us/financial-legal/mifos-contributor-agreement/). +- Always follow the [code of conduct](https://mifos.org/resources/community/code-of-conduct/) - this is important to us. +- Learn more at our [getting started guide](https://mifosforge.jira.com/wiki/spaces/RES/pages/464322561/New+Contributor+Getting+Started+Guide). +- Have a look at our [Wiki](https://github.com/openMF/paymenthub-ee-core/wiki). +- Sign up to Mifos Slack -- main -- master -- dev -- development -- sec -- security -- mifos -- release -- rel -- rc -- staging -- prod -- production -- gsoc -- test -- testing +--- -## Releases +## The Golden Rule: Discuss First -Please always contribute to **Dev**. We then compile accepted PRs from Dev into releases within the community the timing of these releases is. +> **Do not open a Pull Request without prior discussion.** -## Getting Started +We avoid "surprise" contributions. Before writing code, you must validate your idea with the community to ensure it aligns with the roadmap and isn't already in progress. -- View the [README](README.MD) to get your development environment up and running. -- Sign the [Contribution License Agreement](https://mifos.org/about-us/financial-legal/mifos-contributor-agreement/). -- Always follow the [code of conduct](https://mifos.org/resources/community/code-of-conduct/) - this is important to us. We are proud to be open, tolerant and providing a positive environment. -- Introduce yourself or ask a question on the [Mifos Slack](https://mifos.slack.com/ssb/redirect). -- Find a [Jira](https://mifosforge.jira.com/jira/software/c/projects/GAZ/issues?jql=project%20%3D%20%22GAZ%22%20ORDER%20BY%20created%20DESC) ticket to work on. -- If its is already assigned you are not allowed to take it. Instead you must ask the person assigned and they may choose to re-assign it to you. -- If its not assigned you can assign it to yourself. Make sure you keep the status of the ticket up to date and include in comments your progress e.g. screenshots. -- If you need too you can raise a [Jira] ticket on our board for a new feature or enhancement that you want to work on that doesnt have an existing ticket. However its good community spirit to discuss what you are planning in our Slack first. It may also save you wasting time. -- Make sure you have [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed on your machine. -- Fork the repository and clone it locally. +--- -git clone --branch dev https://github.com/openMF/paymenthub-ee-core.git +## Step 1: Discuss on Slack +Before you start coding (especially for new features, UI changes, or refactoring), you must signal your intent. -- Create a new branch for your contributions -git checkout -b feature-branch-name +1. **Join the Community:** [Mifos Slack](https://mifos.slack.com) +2. **Find the Channel:** Navigate to `# channel for repo` +3. **Post Your Proposal:** + - **Features:** Explain what you want to build and why. + - **Bugs:** Briefly explain the issue and provide screenshots if applicable. +4. **Wait for Approval:** Do not proceed until a maintainer or community member acknowledges the task is valid and free for you to take. +--- -## Making Changes +## Step 2: Jira Issue Tracking -- Before making changes, ensure that you're working on the latest version of the `dev` branch +All development work is tracked in Jira to manage the release backlog and ensure transparency. -git pull origin dev +- **System:** [Mifos Jira](https://mifosforge.jira.com) +- **Project:** [PROJECT NAME] +- **Board:** [Board 166](https://mifosforge.jira.com/jira/software/c/projects/MXWAR/boards/166) (Active Development Board) +### Workflow -## Committing Changes +1. **Search:** Check the [Jira Board](https://mifosforge.jira.com/jira/software/c/projects/MXWAR/boards/166) to ensure the ticket doesn't already exist. +2. **Create:** If unique, create a new ticket in Project MXWAR. + - **Summary:** `[Component] Concise description` (e.g., `[Client] Fix submit button alignment`) + - **Description:** Steps to reproduce, expected result, actual result, and environment details. +3. **Assign:** + - Assign the ticket to yourself if you have permissions. + - If you lack permissions, comment "I am working on this" on the ticket and ask a maintainer to assign it to you. +4. **Manage Status:** + - **To Do:** Task is open. + - **In Progress:** Move here immediately when you begin coding. + - **In Review:** Move here when you post the PR link in the comments. + - **Done:** Do not move here. Maintainers will move the ticket to Done after the PR is merged. -- Stage your changes: +--- -git add file-name(s) +## Step 3: Branching Strategy -- Commit your changes with a descriptive message: +We follow a strict branching model to keep our history clean. -git commit -m "Add feature" +- **Upstream Branch:** Always branch from `dev`. Never branch from `master` or `main`. +- **Naming Convention:** Your branch name must include the Jira Ticket ID. + - **Format:** `MXWAR--` + - **Example:** `git checkout -b MXWAR-123-fix-login-button` -- Push your changes to your forked repository: +### Reserved Branch Names -git push origin feature-branch-name +The following branch names and tags (and their derivatives/extensions) are reserved for use by Mifos Organisation. Any branches created by non-admins with these names will be deleted without notice: +- `main` +- `master` +- `dev` +- `development` +- `sec` / `security` +- `mifos` +- `release` / `rel` / `rc` +- `staging` +- `prod` / `production` +- `gsoc` -## Submitting a Pull Request +--- -- Follow the steps outlined in [GitHub's documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) -- The following items are mandatory for all Pull Requests. -- (1) Contributor Licence agreement has been signed -- (2) PR title includes the JIRA ticket reference to allow for tracking -- (3) PR Description explains what you have done, it should include testing and scripts -- (4) You declaire if you have used AI and where. Use of AI is fine but you are expected to have reviewed the output made necessary changes and licence checks and removed any unnecessary AI changes (e.g. removed AI adding of random templates and styles) +## Step 4: UI/UX Consistency -## Commit Hygiene (Squash) +The Web App utilizes React with ShadCN UI and Tailwind CSS. Design consistency is critical for user trust in financial software. + +### Visual Checks + +- **Reference:** Match the Figma mockup or the existing page layout exactly. +- **Grid System:** Spacing must be multiples of 8px (8px, 16px, 24px). Do not use arbitrary values like 10px or 15px. +- **Typography:** Use standard fonts and weights defined in the Tailwind configuration. +- **Components:** Always use ShadCN UI components instead of native HTML tags when possible. + +### Evidence Requirement + +You must attach **"Before"** and **"After"** screenshots to your Pull Request description. PRs involving UI changes without screenshots will be declined. + +--- + +## Step 5: Code Formatting (Prettier) + +We use Prettier to enforce a consistent code style automatically. This eliminates "style wars" in code review. + +- **Configuration:** The project includes a `.prettierrc` or Prettier configuration in `package.json`. +- **Run Prettier:** Before committing, run the following command in the root directory: + ```bash + npx prettier --write . + ``` +- **Linting:** Ensure your code passes linting: + ```bash + npm run lint + ``` + +> ⚠️ If the CI build fails due to formatting or linting errors, your PR will not be reviewed. + +--- + +## Step 6: Commit Hygiene (Squash) We maintain a linear, meaningful git history. - **One Feature = One PR:** Do not combine unrelated fixes. - **Squash Requirement:** If your PR contains more than 2 commits, you must squash them. - ❌ **Bad History:** `init`, `wip`, `typo`, `fix`, `fix again` - - ✅ **Good History:** `GAZ-123: Implement data load functionality` + - ✅ **Good History:** `MXWAR-123: Implement client search functionality` -**How to Squash (Step-by-Step Example):** +**How to Squash (Example for last 2 commits):** -1. **Start Interactive Rebase:** Run the following command (replace `2` with the number of commits you want to combine): +1. **Start Interactive Rebase:** ```bash git rebase -i HEAD~2 ``` -2. **Edit the Rebase File:** An editor will open listing your recent commits. It will look like this: +2. **Edit the Rebase File:** + An editor will open listing the last two commits. It will look similar to this: ```text pick a1b2c3d Message of the older commit pick e4f5g6h Message of the newer commit ``` -3. **Squash the Commits:** Change `pick` to `squash` (or `s`) for all commits except the first one: +3. **Squash the Commits:** + Change the second `pick` to `squash` or `s`: ```text pick a1b2c3d Message of the older commit s e4f5g6h Message of the newer commit ``` -4. **Save and Close:** Save the file and close the editor. +4. **Save and Close:** + Save the file and close the editor. -5. **Finalize Message:** A new editor window will appear. Combine or edit the commit messages into a single, meaningful title (e.g., `GAZ-123: Feature description`). Save and close. +5. **Finalize Message:** + A new editor window will appear allowing you to combine or edit the commit messages for the new, single commit. -6. **Force Push:** Send the changes to your remote repository. +6. **Push the Changes:** + Push the changes to your remote repository: ```bash - git push origin branch-name --force-with-lease + git push --force-with-lease ``` +--- + +## Step 7: Pull Request Checklist + +When you are ready to submit your PR: + +- [ ] **Target:** The `dev` branch. +- [ ] **Title:** Includes the Jira Key (e.g., `MXWAR-123: Fix login button`). +- [ ] **Description:** Includes a link to the Jira ticket. +- [ ] **Context:** Includes a link to the Slack discussion or summary of approval. +- [ ] **Visuals:** "Before" and "After" screenshots are attached (if UI related). +- [ ] **Quality:** Prettier formatting is applied and linting passes. + +--- + +## Additional Resources + +- Learn how to [format pull requests](#best-practices-to-send-pull-requests). +- Read how to [rebase/merge upstream branches](#configuring-remotes). + +## Git and GitHub Workflow + +### Best Practices to send Pull Requests + +- Fork the [project](https://github.com/openMF/paymenthub-ee-core) on GitHub +- Clone the project locally into your system. + +```bash +git clone https://github.com/your-username/paymenthub-ee-core.git +``` + +- We use the `main` branch for releases, hotfixes and special purposes. All regular work on releases flows into the `dev` branch. + +```bash +git checkout dev +``` + +- Create a new branch with a meaningful name before adding and committing your changes. + +```bash +git checkout -b branch-name +``` + +- Add the files you changed. (Better don't use `git add .`) + +```bash +git add file-name +``` + +- Follow the style conventions for a meaningful commit message. + +```bash +git commit +``` + +- If you forgot to add some changes, you can edit your previous commit message. + +```bash +git commit --amend +``` + +- Squash multiple commits to a single commit. (Example: squash last two commits done on this branch into one.) + +```bash +git rebase --interactive HEAD~2 +``` + +- Push this branch to your remote repository on GitHub. + +```bash +git push --set-upstream origin branch-name +``` + +- If any of the squashed commits have already been pushed to your remote repository, you need to do a force push. + + ```bash + git push origin branch-name --force-with-lease + ``` + +- Follow the Pull request template and submit a pull request with a motive for your change and the method you used to achieve it to be merged with the `dev` branch. +- If possible, please submit the pull request along with tests. +- During review, if changes are requested, rebase your branch and squash commits again. Once you push, the pull request updates automatically. + +### Configuring Remotes + +When a repository is cloned, it has a default remote called `origin` that points to your fork on GitHub, not the original repository it was forked from. To keep track of the original repository, you can add another remote called `upstream`. + +1. Set the `upstream`. + +```bash +git remote add upstream https://github.com/openMF/paymenthub-ee-core.git +``` + +2. Use `git remote -v` to check the status. The output must be something like this: + +```bash + > origin https://github.com/your-username/paymenthub-ee-core.git (fetch) + > origin https://github.com/your-username/paymenthub-ee-core.git (push) + > upstream https://github.com/openMF/paymenthub-ee-core.git (fetch) + > upstream https://github.com/openMF/paymenthub-ee-core.git (push) +``` + +3. To update your local copy with remote changes, run the following: (This will give you an exact copy of the current remote. You should not have any local changes on your dev branch, if you do, use rebase instead.) + +```bash +git fetch upstream +git checkout dev +git merge upstream/dev +``` + +4. Push these merged changes to the `dev` branch on your fork. (Pull upstream changes regularly to keep your fork up to date, or use the "Sync fork" button at the top of your fork's GitHub page, then run `git pull`.) + +```bash +git push origin dev +``` + +5. Switch to the branch you are using for some piece of work. + +```bash +git checkout branch-name +``` + +6. Rebase your branch, which means, take in all latest changes and replay your work in the branch on top of this - this produces cleaner versions/history. + +```bash +git rebase dev +``` + +7. Push the final changes when you're ready. + +```bash +git push origin branch-name +``` + +### After your Pull Request is merged + +After your pull request is merged, you can safely delete your branch and pull the changes from the dev (upstream) repository. + +1. Delete the remote branch on GitHub. + +```bash +git push origin --delete branch-name +``` + +2. Checkout the dev branch. + +```bash +git checkout dev +``` + +3. Delete the local branch. + +```bash +git branch -D branch-name +``` -## Code Review +4. Update your dev branch with the latest upstream version. -- After submitting your PR, our team will review your changes. -- Address any feedback or requested changes promptly. -- Once approved, your PR will be merged into the `dev` branch. -- Every release we will take the release from the 'dev' branch to the 'main' branch +```bash +git pull upstream dev +``` -## After your PR is merged +### Skipping a CI Build -After your PR has been reviewed any feedback taken on board and merged there are a few things to keep things tidy we like you to do. -- Delete your branch unless you think it will be needed again -- update Jira status to `DONE` if its the last PR you need to raise to address a ticket. **Do not do this if you will need to raise another PR to fully address the scope or if its still in PR review.** +If running a build is not required for a particular commit (in some cases like an update to README.md), add [ci skip] or [skip ci] to the git commit message. Commits that have [ci skip] or [skip ci] anywhere in the commit messages are ignored by CI. -## Reporting Issues +--- -If you find any bugs or have recommendations for improvements, please feel free to [raise a bug here](https://mifosforge.jira.com/jira/software/c/projects/GAZ/issues?jql=project%20%3D%20%22GAZ%22%20ORDER%20BY%20created%20DESC) with a detailed explanation of issue ideally including steps to reproduce and screenshots/video. +## Getting Help -## Contact +If you get stuck, please reach out in the `#web-app` channel on [Slack](https://mifos.slack.com). We are happy to help you navigate the codebase or troubleshoot environment issues! -- For further assistance or questions regarding contributions, feel free to join our Slack channel [here](https://mifos.slack.com/ssb/redirect). If you need an invite you can use this [link](https://join.slack.com/t/mifos/shared_invite/zt-3m6x47dgj-iX0Oqv8KS0VGgouNnuJrAg) +--- -Thank you again for your interest in [paymenthub-ee-core](https://github.com/openMF/paymenthub-ee-core)! We look forward to your contributions. +**_Thank you for contributing!_**