Guidelines:DeveloperWorkflow - Revision history

Dominic: Blanked the page

2025-10-23T15:23:41Z

Blanked the page

Dominic: /* Testing Your Code */

2025-10-23T15:22:29Z

Testing Your Code

← Older revision		Revision as of 15:22, 23 October 2025
Line 136:		Line 136:
	=== Testing Your Code ===		=== Testing Your Code ===

	When you submit a pull request, we expect that you have test-run the new or modified code and verified that it works correctly as intended. If a pull request contains obvious programming mistakes or design flaws that prevent it from working ~~properly~~, we will reject the pull request outright.		When you submit a pull request, we expect that you have test-run the new or modified code and verified that it works correctly as intended. If a pull request contains obvious programming mistakes or design flaws that prevent it from working at all, we will reject the pull request outright.

	=== Experimental Code ===		=== Experimental Code ===

Dominic: /* Testing Your Code */

2025-10-23T15:21:56Z

Testing Your Code

← Older revision		Revision as of 15:21, 23 October 2025
Line 136:		Line 136:
	=== Testing Your Code ===		=== Testing Your Code ===

	When you submit a pull request, we expect that you have test-run the new or modified code and verified that it works correctly as intended. If a pull request contains obvious programming mistakes, we will reject the pull request outright.		When you submit a pull request, we expect that you have test-run the new or modified code and verified that it works correctly as intended. If a pull request contains obvious programming mistakes or design flaws that prevent it from working properly, we will reject the pull request outright.

	=== Experimental Code ===		=== Experimental Code ===

Dominic: /* Experimental Code */

2025-10-23T15:21:00Z

Experimental Code

← Older revision		Revision as of 15:21, 23 October 2025
Line 144:		Line 144:
	If you want to discuss an idea before investing more time to make it actually work, or share some incomplete changes with fellow developers for them to continue the work, you can do so by publishing your story branch and pointing to it in a mailing list discussion. Other developers can then pull the experimental changes directly from your fork repository - so there is no need to exchange such code via the sahana/eden dev branch.		If you want to discuss an idea before investing more time to make it actually work, or share some incomplete changes with fellow developers for them to continue the work, you can do so by publishing your story branch and pointing to it in a mailing list discussion. Other developers can then pull the experimental changes directly from your fork repository - so there is no need to exchange such code via the sahana/eden dev branch.

	However, sometimes you may want to publish a preview version of a new feature, in order to get feedback from users or fellow developers before continuing the work. In such cases, you should mark your pull request with UAT (=user acceptance testing) to indicate your intention. ~~In this case~~, ~~the changes~~ can be incomplete, but they should work at least so that they can be tested. It is also required that UAT-stage feature sets are disabled by default, typically using a deployment setting.		However, sometimes you may want to publish a preview version of a new feature, in order to get feedback from users or fellow developers before continuing the work. In such cases, you should mark your pull request with UAT (=user acceptance testing) to indicate your intention. For UAT, change sets can be incomplete, but they should work at least so that they can be tested. It is also required that UAT-stage feature sets are disabled by default, typically using a deployment setting.

Dominic at 15:18, 23 October 2025

2025-10-23T15:18:12Z

← Older revision		Revision as of 15:18, 23 October 2025
Line 121:		Line 121:
	git branch -d story_branch		git branch -d story_branch
	git push -d origin story_branch		git push -d origin story_branch

			== Best Practices ==

			=== Story Branches ===

			While you could commit your changes directly to your dev branch and create a pull request from there, we strongly advise against that practice. Unless you are working only on one small change, and do not intend to reuse your local instance for further work any time soon, you should be working in story branches.

			=== Separating Topics ===

			A pull request should only deal with one set of changes that are closely related to each other. If you are working on multiple topics, or complex change sets that touch many areas, you should separate these into multiple pull requests. Pull requests that are too large or complex to be meaningfully reviewed, can be rejected for that reason alone - therefore: make it coherent and digestible.

			This may not always be possible: if you are e.g. creating a new template or theme, the first working version of it may involve many new files at once. In such cases, it can make sense to discuss it beforehand on the mailing list, and to provide a demo, or at least some screenshots, to aid the reviewer. Such larger change sets always require a [[Blueprint:Blueprint\|Blueprint]] to get accepted.

			=== Testing Your Code ===

			When you submit a pull request, we expect that you have test-run the new or modified code and verified that it works correctly as intended. If a pull request contains obvious programming mistakes, we will reject the pull request outright.

			=== Experimental Code ===

			Code changes proposed in pull requests should be fully working and fulfilling their purpose. Experimental changes will normally be rejected.

			If you want to discuss an idea before investing more time to make it actually work, or share some incomplete changes with fellow developers for them to continue the work, you can do so by publishing your story branch and pointing to it in a mailing list discussion. Other developers can then pull the experimental changes directly from your fork repository - so there is no need to exchange such code via the sahana/eden dev branch.

			However, sometimes you may want to publish a preview version of a new feature, in order to get feedback from users or fellow developers before continuing the work. In such cases, you should mark your pull request with UAT (=user acceptance testing) to indicate your intention. In this case, the changes can be incomplete, but they should work at least so that they can be tested. It is also required that UAT-stage feature sets are disabled by default, typically using a deployment setting.

Dominic at 13:30, 23 October 2025

2025-10-23T13:30:08Z

← Older revision		Revision as of 13:30, 23 October 2025
Line 2:		Line 2:

	== Developer Workflow ==		== Developer Workflow ==

			This page gives and overview over the workflow for contributing code to the Sahana Eden code base.

			Please note that this is just a general outline - for more details on how to work with ''git'' or ''GitHub'', please refer to their respective documentations.

	=== Prerequisites ===		=== Prerequisites ===

Dominic at 13:27, 23 October 2025

2025-10-23T13:27:37Z

← Older revision		Revision as of 13:27, 23 October 2025
Line 66:		Line 66:
	=== Publishing Changes ===		=== Publishing Changes ===

	To ~~publish~~ your changes, ~~commit~~ them to the story branch:		To get your changes merged into Sahana Eden, start by committing them to the story branch:

	git checkout story_branch		git checkout story_branch
	git commit -a		git commit -a

	...and then ~~push that~~ branch to your GitHub repo:		Before publishing the changes, it may be necessary that you rebase your story branch on the latest version of the upstream dev branch. To do so, first update your local dev branch:

			git checkout dev
			git pull upstream dev

			...and then rebase your story branch on it:

			git checkout story_branch
			git rebase dev

			Finally, publish your changes by pushing them to your GitHub repo:

	git push origin story_branch		git push origin story_branch
Line 86:		Line 96:
	* against the sahana/eden dev branch (base repository)		* against the sahana/eden dev branch (base repository)

	Create a pull request (rather than a draft pull request) to submit your changes for review. Anyone can comment on your pull request, and you can discuss with them directly on GitHub. If you need to modify your changes in order to get them accepted, make the modifications locally, commit them and push to your story branch again:		Create a pull request (rather than a draft pull request) to submit your changes for review. Anyone can comment on your pull request, and you can discuss with them directly on GitHub.

			If you need to modify your changes in order to get them accepted, make the modifications locally, commit them and push to your story branch again:

	git checkout story_branch		git checkout story_branch
Line 93:		Line 105:

	This will automatically update your pull request with the new commit.		This will automatically update your pull request with the new commit.

	~~It may be necessary that you rebase your story branch on a newer version of the upstream dev branch. To do so, first update your local dev branch:~~

	~~git checkout dev~~
	~~git pull upstream dev~~

	~~...and then rebase your story branch on it, and push to your remote story branch again to update the pull request:~~

	~~git checkout story_branch~~
	~~git rebase dev~~

	Eventually, a maintainer will decide whether to accept and merge your changes, or to reject them.		Eventually, a maintainer will decide whether to accept and merge your changes, or to reject them.

Dominic: /* Submitting Pull Requests */

2025-10-23T13:24:02Z

Submitting Pull Requests

@@ Line 86: / Line 86: @@
 * against the sahana/eden dev branch (base repository)
-Create a pull request (rather than a draft pull request) to submit your changes for review. Anyone can comment on your pull request, and you can discuss with them directly on GitHub.
+Create a pull request (rather than a draft pull request) to submit your changes for review. Anyone can comment on your pull request, and you can discuss with them directly on GitHub. If you need to modify your changes in order to get them accepted, make the modifications locally, commit them and push to your story branch again:
 Eventually, a maintainer will decide whether to accept and merge your changes, or to reject them.

Dominic at 13:19, 23 October 2025

2025-10-23T13:19:02Z

← Older revision		Revision as of 13:19, 23 October 2025
Line 27:		Line 27:
	When you get to [https://eden-asp.readthedocs.io/en/latest/dev/setup.html#installing-eden '''Installing Eden'''], make sure to clone your own fork:		When you get to [https://eden-asp.readthedocs.io/en/latest/dev/setup.html#installing-eden '''Installing Eden'''], make sure to clone your own fork:

	~~<code>~~		git clone --recursive https://github.com/[yourname]/eden.git ~/eden
	git clone --recursive https://github.com/[yourname]/eden.git ~/eden
	~~</code>~~

	...instead of ''sahana/eden''.		...instead of ''sahana/eden''.
Line 35:		Line 33:
	Finally, configure ''sahana/eden'' as upstream repository for your clone:		Finally, configure ''sahana/eden'' as upstream repository for your clone:

	~~<code>~~		git remote add upstream https://github.com/sahana/eden.git
	git remote add upstream https://github.com/sahana/eden.git
	~~</code>~~

	Now you can use this local instance to test-run and verify your changes.		Now you can use this local instance to test-run and verify your changes.
Line 45:		Line 41:
	All development should be based on the <code>dev</code> branch of ''sahana/eden''. To get a copy of that branch into your local clone, change into the ''eden'' folder and run these two commands:		All development should be based on the <code>dev</code> branch of ''sahana/eden''. To get a copy of that branch into your local clone, change into the ''eden'' folder and run these two commands:

	~~<code>~~		git checkout -b dev
	git checkout -b dev		git pull upstream dev
	~~</code>~~

	~~<code>~~
	git pull upstream dev
	~~</code>~~

	This adds a copy of the Sahana Eden dev branch to your local clone, and checks out the latest developer version of the code.		This adds a copy of the Sahana Eden dev branch to your local clone, and checks out the latest developer version of the code.
Line 61:		Line 52:
	To create a new story branch, change into your eden folder, and checkout the dev branch:		To create a new story branch, change into your eden folder, and checkout the dev branch:

	~~<code>~~		git checkout dev
	git checkout dev
	~~</code>~~

	From this, create the new story branch:		From this, create the new story branch:

	~~<code>~~		git checkout -b story_branch
	git checkout -b story_branch
	~~</code>~~

	...replacing ''story_branch'' with a descriptive name for the change set (e.g. ''bugfix_org_menu'').		...replacing ''story_branch'' with a descriptive name for the change set (e.g. ''bugfix_org_menu'').

	You can have multiple story branches, and switch between them. However, remember that you should either stash or commit your changes before switching branches.		Make your changes to the story branch, and test-run and verify them with your local instance.

			You can have multiple story branches, and switch between them. However, remember that you should either stash or commit your changes before switching branches. Further, you make changes to data models, only the story branch will have them - so it will become necessary to reset the database of your local instance when switching branches.

	=== Publishing Changes ===		=== Publishing Changes ===
Line 79:		Line 68:
	To publish your changes, commit them to the story branch:		To publish your changes, commit them to the story branch:

	~~<code>~~		git checkout story_branch
	git commit -a		git commit -a
	~~</code>~~

	...and then push that branch to your GitHub repo:		...and then push that branch to your GitHub repo:

	~~<code>~~		git push origin story_branch
	git push origin ~~story_branch_name~~
	~~</code>~~

	This will copy the story branch to your repository on GitHub, or update that branch if it already exists ~~there~~.		This will copy the story branch to your repository on GitHub, or update that branch there if it already exists.

	=== Submitting Pull Requests ===		=== Submitting Pull Requests ===

Dominic: /* Submitting Pull Requests */

2025-10-23T13:14:08Z

Submitting Pull Requests

← Older revision		Revision as of 13:14, 23 October 2025
Line 93:		Line 93:
	=== Submitting Pull Requests ===		=== Submitting Pull Requests ===

	To get your changes merged into the main Sahana Eden repository, you need to submit a pull request.		To get your changes merged into the main Sahana Eden repository, you need to submit a pull request. Follow the [https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork GitHub documentation] to create a pull request.

			Make sure that you compare:

			* your story branch (head repository)
			* against the sahana/eden dev branch (base repository)

			Create a pull request (rather than a draft pull request) to submit your changes for review. Anyone can comment on your pull request, and you can discuss with them directly on GitHub.

			Eventually, a maintainer will decide whether to accept and merge your changes, or to reject them.

			Once they have been merged successfully into the sahana/eden dev branch, you can update your local copy of it:

			git checkout dev
			git pull upstream dev

			You can also discard your story branch:

			git branch -d story_branch
			git push -d origin story_branch