在此文中
In order to contribute to the BananaAccounting GitHub repository and submit your changes it is necessary to follow some basic steps:
- Install GitHub Desktop
- Clone the repository
- Create a new Branch
- Modify or add files to the repository
- Keep in sync with the BananaAccounting repository
(Repeat this step frequently!! It downloads the changes from the BananaAccounting main repository into your local repository, preventing conflicts). - Submit the changes
anchor
Install Github Desktop
Install GitHub Desktop on your computer, and (if you don't have it already) create your own account.
anchor
Clone the repository
The second step is to clone the forked repository:
- Click the green button Clone or download -> Open in Desktop -> . GitHub Desktop should automatically open.
- Choose a path on your local machine to clone the repository.
- Click the button Clone and wait a moment while the forked repository is cloned on your local machine.
At this point, you have created on your computer your own copy of the repository.
anchor
Create a new Branch
In order to complete this phase you have to do the following steps:
- In GitHub Desktop press the upper and centered button Current Branch -> New Branch -> Insert in the window that just appeared the name for the Branch.
- Choose the Branch from which you want to fork, by default is master.
- Click the button Create Branch.
- Click the blue button Publish branch.
Now you have your own Branch to work on the project.
anchor
Modify or add files to the repository
To work with the repository:
- Start GitHub Desktop
- Choose the repository you want to work on
- Menu Repository -> Show in Explorer
- Work on the repository, create and/or edit the files that you wish to change.
- Open GitHub desktop again, your changes should be visible on the left side of the window.
- Commit the changes to your own repository by clicking on Commit to <your_branch_name>.
- Click the blue button Push Origin.
anchor
Sync your branch with the master branch
This is a fundamental step, which should be repeated multiple time when you're modifying files of a repository, by repeating this process you avoid conflicts with the master branch.
In order to Sync a fork of a repository to keep it up-to-date with the upstream repository follow the following step:
Open GitHub Desktop -> Click the upper button on the right Fetch origin
Now your branch should be in sync with the project master branch.
Submit the changes (Pull request)
To submit changes with GitHub desktop:
- Start GitHub Desktop
- Choose the repository
- Click the blue button Create Pull Request
- You should be redirected to your browser on the GitHub page of the project, here add a comment title and a comment text for the pull request, it helps a lot for other people to understand what you changed so be precise and follow these two steps:
- Explain exactly what changes you have made, so that the moderator can more easily accept the changes.
It will also help you later to understand what has been done.
It it is worth to dedicate some time to doing good comments. - You can comment also groups of files you have changed. (see github documentation).
- Explain exactly what changes you have made, so that the moderator can more easily accept the changes.
- Click the button Create Pull Request
- Will appear a message which will verify if you branch has created conflicts, in order to avoid them remember to repeat more and more times the Sync forked repository with the master repository step.
The repository moderator will receive the pull request, evaluate and approve or refuse the contribution.
You will be notified by email when the pull request has been accepted.
Important:
- Do not click on the "Close Pull Request" button, or the pull request will be blocked!
- If the system tell you that there are conflicts, you should not submit the pull request.
Conflicts are probably due to the fact that you have not synched you repository with the Banana Accounting repository.
Eventually:- do a copy of your repository.
- resync again or in case clone again the main repository.
- copy the changed files from the copy repository to the correct one.
- Redo the pull request process.