If you want to contribute to a project and make it better, your help is very welcome. Please see below instructions how to contribute.
- How to Contribute
Perform following section only once at the beginning of your contribution.
Detailed instructions are here: https://help.github.com/en/articles/signing-up-for-a-new-github-account
Adding SSH key will enable password-less connectivity to GitHub.
Detailed instructions are here: https://help.github.com/en/articles/adding-a-new-ssh-key-to-your-github-account
Forking the devel repository will create your own personal copy of the repository.
-
Navigate to the project repository: https://github.com/sap-architecture-devel/sap-hana
-
Click on
Forkbutton in upper-right corner of the page
-
Select your user to create copy in your private space
-
As result you should see that repository was forked to your personal space:
Detailed instructions are here: https://help.github.com/en/articles/fork-a-repo
Clone your personal copy of the repository to your workstation.
-
Navigate to the forked repository:
https://github.com/<YOUR-USER>/sap-hana -
Click
Clone or downloadbutton in upper-right corner of the page
Note: In order to use SSH to connect to GitHub you need to click on
Use SSHin upper-right corner of the panel -
Copy the URL from the panel:
[email protected]:<YOUR-USER>/sap-hana.git -
Open Terminal and change directory to desired location
-
Run
gitcommand to clone the repository# git clone [email protected]:<YOUR-USER>/sap-hana.git Cloning into 'sap-hana'... remote: Enumerating objects: 7, done. remote: Counting objects: 100% (7/7), done. remote: Compressing objects: 100% (6/6), done. remote: Total 7 (delta 0), reused 3 (delta 0), pack-reused 0 Receiving objects: 100% (7/7), done.
Detailed instructions are here: https://help.github.com/en/articles/fork-a-repo
Configure forked repository synchronization with main project repository.
-
Open Terminal and change directory to location of your local copy of the repository:
cd /path-to-your-repository/sap-hana -
List currently defined remote repositories:
# git remote -v origin [email protected]:<YOUR-USER>/sap-hana.git (fetch) origin [email protected]:<YOUR-USER>/sap-hana.git (push)
-
Add link to main project repository:
git remote add upstream [email protected]:sap-architecture-devel/sap-hana.git -
List again defined remote repositories:
# git remote -v origin [email protected]:<YOUR-USER>/sap-hana.git (fetch) origin [email protected]:<YOUR-USER>/sap-hana.git (push) upstream [email protected]:sap-architecture-devel/sap-hana.git (fetch) upstream [email protected]:sap-architecture-devel/sap-hana.git (push)
Detailed instructions are here: https://help.github.com/en/articles/fork-a-repo
Perform following section on regular basis and always before you create Pull Request to main project.
Download and merge new updates from main project repository into your local repository on your workstation.
-
Open Terminal and change directory to location of your local copy of the repository:
cd /path-to-your-repository/sap-hana -
Fetch the branches and their content from the main project repository:
# git fetch upstream remote: Enumerating objects: 13, done. remote: Counting objects: 100% (13/13), done. remote: Compressing objects: 100% (10/10), done. remote: Total 11 (delta 0), reused 10 (delta 0), pack-reused 0 Unpacking objects: 100% (11/11), done. From github.com:sap-architecture-devel/sap-hana * [new branch] master -> upstream/master
-
Change local repository branch to
master# git checkout master Already on 'master' Your branch is up to date with 'origin/master'.
-
Merge changes from
upstream/masterinto your localmasterbranch# git merge upstream/master Updating 11569ab..469f8ab Fast-forward CHANGELOG.md | 5 +++++ CONTRIBUTING.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ README.md | 3 ++- images/contributing-clone-1.png | Bin 0 -> 18798 bytes images/contributing-fork-1.png | Bin 0 -> 6350 bytes images/contributing-fork-2.png | Bin 0 -> 15140 bytes images/contributing-fork-3.png | Bin 0 -> 12140 bytes 7 files changed, 53 insertions(+), 1 deletion(-) create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 images/contributing-clone-1.png create mode 100644 images/contributing-fork-1.png create mode 100644 images/contributing-fork-2.png create mode 100644 images/contributing-fork-3.png
-
In case there were merge conflicts you need to resolve them as described in https://help.github.com/en/articles/resolving-a-merge-conflict-using-the-command-line
Detailed instructions are here: https://help.github.com/en/articles/syncing-a-fork
Upload merged content from your local repository on your workstation to your GitHub repository.
-
Open Terminal and change directory to location of your local copy of the repository:
cd /path-to-your-repository/sap-hana -
Upload the merged content in active branch to your GitHub repository
# git push Total 0 (delta 0), reused 0 (delta 0) To github.com:<YOUR-USER>/sap-hana.git 11569ab..469f8ab master -> master
-
Now you can see the content online in your own personal copy of the repository in GitHub:
https://github.com/<YOUR-USER>/sap-hana
Detailed instructions are here: https://help.github.com/en/articles/pushing-commits-to-a-remote-repository
Deliver new content by editing files on your local workstation, push to online GitHub and review.
The documentation is written in Markdown language.
Additional information about Markdown:
- Basic writing and formatting syntax
- Working with advanced formatting
- Mastering Markdown
- GitHub Flavored Markdown Spec
Images should be uploaded into subdirectory images below directory where the page referencing the image is located.
Files should be uploaded into subdirectory files below directory where the page referencing the image is located.
Make sure you name all images and files in clear way.
All links to pages, images or files located in this repository should be based on relative paths - avoid using absolute paths as this will break the link functionality in forked repositories.
Use your favorite editor to add new content. Use Linting function to deliver clean and well-structured documentation.
Recommended editors:
- Visual Studio Code
- plugin Markdown All in One
- plugin Markdown Lint
- plugin Auto Markdown TOC
- Atom Editor
When unit of work is completed commit the changes to your local repository on your local workstation.
Use either your editor to commit the changes (recommended) or perform following commands:
-
Open Terminal and change directory to location of your local copy of the repository:
cd /path-to-your-repository/sap-hana -
Check the status
# git status On branch master Your branch is up to date with 'origin/master'. Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git checkout -- <file>..." to discard changes in working directory) modified: CONTRIBUTING.md no changes added to commit (use "git add" and/or "git commit -a")
Note: In example above we can see file
CONTRIBUTING.mdis NOT part of commit. -
Add files that should be included in commit
- Add individual files:
git add <file_name> - Add directory:
git add <directory_name>
In order to add all files, perform
git add . - Add individual files:
-
Check the status again
# git status On branch master Your branch is up to date with 'origin/master'. Changes to be committed: (use "git reset HEAD <file>..." to unstage) modified: CONTRIBUTING.md
-
Commit changes to active branch
# git commit -m "Update to CONTRIBUTING.md" [master d6a2568] Update to CONTRIBUTING.md 1 file changed, 1 insertion(+), 1 deletion(-)
Detailed instructions are here: https://help.github.com/en/articles/adding-a-file-to-a-repository-using-the-command-line
Push your local changes from your local repository on your workstation to your GitHub repository.
-
Open Terminal and change directory to location of your local copy of the repository:
cd /path-to-your-repository/sap-hana -
Push changes from active branch to your GitHub repository
# git push Enumerating objects: 8, done. Counting objects: 100% (8/8), done. Delta compression using up to 12 threads Compressing objects: 100% (6/6), done. Writing objects: 100% (6/6), 3.23 KiB | 3.23 MiB/s, done. Total 6 (delta 3), reused 0 (delta 0) remote: Resolving deltas: 100% (3/3), completed with 1 local object. To github.com:<YOUR-USER>/sap-hana.git 469f8ab..d6a2568 master -> master
-
Review your changes online in your own personal copy of the repository in GitHub:
https://github.com/<YOUR-USER>/sap-hana
Detailed instructions are here: https://help.github.com/en/articles/adding-a-file-to-a-repository-using-the-command-line
Create Pull Request (PR) from your own GitHub repository against main project repository.
Very likely your updates took some time. Meanwhile the content in main project repository changed and might be out of sync with your own repository.
Follow procedure described in section 2. Recurrent synchronization.
Make sure you document what was changed in CHANGELOG.md file. Make sure this very last change to avoid merge conflicts.
Follow procedure described in section 3. Add new Content and Commit to adjust the file.
Before you create Pull Request (PR) make sure that:
- you downloaded and merged latest content from main project repository
- you resolved all merge conflicts
- you pushed all changes from your local repository on your workstation to online GitHub repository
- you reviewed your content online in GitHub
https://github.com/<YOUR-USER>/sap-hanaand confirmed the content is rendering correctly - that includes:- all images are properly displayed (and are relative)
- all links are working properly (and are relative is pointing to page in same repository)
-
Navigate to the forked repository:
https://github.com/<YOUR-USER>/sap-hana -
Click
New pull requestbutton in upper-left part of the page
-
Review the Pull Request (PR) details
Note: On left side you see destination (main project repository) and on left side you see source (your own forked repository).
-
In case all visualized changes are ok press
Create pull requestbutton
-
Add title and meaningful description and click
Create pull requestbutton
-
Wait for your Pull Request to be reviewed and respond to any request for changes
Note: Until your Pull Request is accepted all your commits that are pushed to your forked repository in GitHub will be automatically included in given Pull Request.
If you want to make commits that are not included in Pull Request, consider using separate branch for your updates.
Detailed instructions are here: https://help.github.com/en/articles/creating-a-pull-request-from-a-fork