|
|
| (8 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:
| |
|
| |
| <code>
| |
| git clone --recursive https://github.com/[yourname]/eden.git ~/eden
| |
| </code>
| |
|
| |
| ...instead of ''sahana/eden''.
| |
|
| |
| Finally, configure ''sahana/eden'' as upstream repository for your clone:
| |
|
| |
| <code>
| |
| 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.
| |
|
| |
| === 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:
| |
|
| |
| <code>
| |
| git checkout -b 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.
| |
|
| |
| === 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:
| |
|
| |
| <code>
| |
| git checkout dev
| |
| </code>
| |
|
| |
| From this, create the new story branch:
| |
|
| |
| <code>
| |
| git checkout -b story_branch
| |
| </code>
| |
|
| |
| ...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.
| |
|
| |
| === Publishing Changes ===
| |
|
| |
| To publish your changes, commit them to the story branch:
| |
|
| |
| <code>
| |
| git commit -a
| |
| </code>
| |
|
| |
| ...and then push that branch to your GitHub repo:
| |
|
| |
| <code>
| |
| 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.
| |
|
| |
| === 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.
| |
|
| |
| 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
| |
