|
|
| (6 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| * [[Guidelines:Index|All Guidelines]]
| |
|
| |
|
| == Developer Workflow ==
| |
|
| |
| === Prerequisites ===
| |
|
| |
| Additionally, you will need:
| |
|
| |
| * [https://git-scm.com '''git''']
| |
| * a suitable programming editor (e.g. [https://kate-editor.org Kate])
| |
|
| |
| === Forking Sahana Eden ===
| |
|
| |
| Start by creating your own fork of '''Sahana Eden''':
| |
| * Login to [https://github.com|'''GitHub'''] (create yourself an account, if you don't have one yet)
| |
| * Navigate to https://github.com/sahana/eden
| |
| * Click on the '''Fork''' button, and follow the instructions to create a new fork
| |
|
| |
| This will create a new GitHub repository ''[yourname]/eden''<sup>*</sup>, which is your own copy of ''sahana/eden'' - and the repository you will work on.
| |
|
| |
| <sup>*</sup> ''[yourname] here stands for your GitHub username''
| |
|
| |
| === Creating a Local Clone ===
| |
|
| |
| Follow the steps in the [https://eden-asp.readthedocs.io/en/latest/dev/setup.html '''Developer Handbook'''] to set up a local instance of Sahana Eden.
| |
|
| |
| 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:
| |
|
| |
| git clone --recursive https://github.com/[yourname]/eden.git ~/eden
| |
|
| |
| ...instead of ''sahana/eden''.
| |
|
| |
| Finally, configure ''sahana/eden'' as upstream repository for your clone:
| |
|
| |
| git remote add upstream https://github.com/sahana/eden.git
| |
|
| |
| Now you can use this local instance to test-run and verify your changes.
| |
|
| |
| === Adding the Development Branch ===
| |
|
| |
| 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:
| |
|
| |
| git checkout -b dev
| |
| git pull upstream dev
| |
|
| |
| This adds a copy of the Sahana Eden dev branch to your local clone, and checks out the latest developer version of the code.
| |
|
| |
| === Creating Story Branches ===
| |
|
| |
| Rather than making changes in the dev branch directly, you should use a new branch for every set of changes you make, a so-called '''story branch'''.
| |
|
| |
| To create a new story branch, change into your eden folder, and checkout the dev branch:
| |
|
| |
| git checkout dev
| |
|
| |
| From this, create the new story branch:
| |
|
| |
| git checkout -b story_branch
| |
|
| |
| ...replacing ''story_branch'' with a descriptive name for the change set (e.g. ''bugfix_org_menu'').
| |
|
| |
| 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 ===
| |
|
| |
| To publish your changes, commit them to the story branch:
| |
|
| |
| git checkout story_branch
| |
| git commit -a
| |
|
| |
| ...and then push that branch to your GitHub repo:
| |
|
| |
| git push origin story_branch
| |
|
| |
| This will copy the story branch to your repository on GitHub, or update that branch there if it already exists.
| |
|
| |
| === Submitting Pull Requests ===
| |
|
| |
| 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. 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 commit -a
| |
| git push origin story_branch
| |
|
| |
| 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.
| |
|
| |
| 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
| |
