1

Home

Llewellyn edited this page 2023-03-22 04:44:26 +00:00

Table of Contents

• Prepare environment
• You will need to install git:
• Setup SSH and link to https://git.vdm.dev.
• Setup a GPG key and link to https://git.vdm.dev.
• Link GPG to Git
• Contributing to the project
• Step 1: Fork the Repository
• Step 2: Clone Your Forked Repository
• Step 3: Change to the Repository Directory
• Step 4: Create a New Branch
• Step 5: Make Commits
• Step 6: Push Your Branch
• Step 7: Create a Pull Request
• Updating Your Local Branch After a Successful Merge
• Step 1: Make sure you are on the Master Branch
• Step 2: Add the Original Repository as a Remote
• Step 3: Fetch Changes from the Original Repository
• Step 4: Merge the Changes into Your Local Master Branch
• Step 5: Push the Changes to Your Forked Repository
• Adding more Changes to the Project
• Step 1: Make Sure You Are on the Master Branch
• Step 2: Create a New Branch for the New Feature
• Step 3: Make Changes and Commits
• Step 4: Push Your Branch
• Step 5: Create a New Pull Request

Here we will look at the first steps to start contributing, more Scripture.

You need a Afrikaans 1933 version of the Afrikaans Bible. Reading this we assume you have a computer. But for most convenient use you need Linux Ubuntu as your Operating System. This manual will only be directed towards the Ubuntu (linux) OS. Should you be on another kind of Operating System, you will need to know how to achieve the same outcome in that environment.

Prepare environment

You will need to install git:

1. Install Git by running:

sudo apt update
sudo apt install git

2. Configure Git to use your name and email (the same you used for your SSH and GPG keys) by running:

git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"

Replace "Your Name" with your actual name, and "your_email@example.com" with your actual email address.

Setup SSH and link to https://git.vdm.dev.

1. Open a terminal on your Ubuntu system.
2. Generate an SSH key pair by running the following command:

ssh-keygen -t ed25519 -C "your_email@example.com"

3. Replace "your_email@example.com" with your actual email address. The -t ed25519 flag specifies the key type (in this case, Ed25519), and -C is used to add a comment (usually your email) for easier identification.
4. When prompted to enter a file in which to save the key, press Enter to accept the default location (~/.ssh/id_ed25519).
5. Next, you'll be asked to enter a passphrase. You can either enter a secure passphrase or leave it empty for no passphrase. Press Enter.
6. Your SSH key pair is now generated. You can view your public key by running:

cat ~/.ssh/id_ed25519.pub

7. Copy the output (your public key).

8. Now, you need to add this SSH key to your Gitea account:

   a. Log in to your Gitea instance.

   b. Click on your profile picture in the top right corner, and select "Settings."

   c. In the left sidebar, click on "SSH / GPG Keys."

   d. Click on the "Add Key" button.

   e. Paste your public key (copied public key) into the "Content" field, and provide a title for the key (e.g., "Ubuntu workstation").

   f. Click on the "Add Key" button to save the key.

   g. Now you can verify the SSH key by following the instructions that Gitea gives you when clicking on Verify Key .

9. Configure Git to use your SSH key:

Since you already generated an SSH key and added it to your Gitea account, Git will automatically use your SSH key when you clone or interact with repositories using the git@ URL format.

To ensure your SSH key is used, when cloning a Gitea repository, use the SSH URL (which starts with git@). For example:

git clone ssh://git@git.vdm.dev/[yourname]/Afrikaans-1933.git

Setup a GPG key and link to https://git.vdm.dev.

1. Install GnuPG on your Ubuntu system (if not already installed) by running:

sudo apt update
sudo apt install gnupg

2. Generate a new GPG key by running:

gpg --full-generate-key

3. Choose the key type (usually RSA), key size (2048 or 4096 bits), and expiration date (you can use "0" for no expiration).

4. Enter your name, email, and an optional comment. These will be associated with the GPG key.

5. Choose a secure passphrase to protect your GPG key. Remember this passphrase, as you will need it to use the key.

6. After generating the key, list your GPG keys with:

gpg --list-secret-keys --keyid-format LONG

7. Locate your key in the output and note down the GPG key ID. It's the part after the / in the sec line (e.g., A27DE0114241CAA6 in sec rsa4096/0xA27DE0114241CAA6 2023-03-15 [SC]).

8. Export your public GPG key by running:

gpg --armor --export <your_GPG_key_ID>

Replace <your_GPG_key_ID> with the key ID noted in step 7. Copy the output (your public GPG key).

10. Now, add this GPG key to your Gitea profile:

    a. Log in to your Gitea instance.

    b. Click on your profile picture in the top right corner, and select "Settings."

    c. In the left sidebar, click on "SSH / GPG Keys."

    d. Switch to the "GPG Keys" tab.

    e. Click on the "Add GPG Key" button.

    f. Paste your public GPG key (copied from step 8) into the "Content" field.

    g. Click on the "Add GPG Key" button to save the key.

    h. Now you can verify the GPG key by following the instructions that Gitea gives you when clicking on Verify Key.

Your GPG key is now set up on your Ubuntu system, and you've added it to your Gitea account. You can use this key to sign your commits and verify your identity in Gitea.

Link GPG to Git

1. First, get your GPG key ID by running:

gpg --list-secret-keys --keyid-format LONG

2. Locate your key in the output and note down the GPG key ID. It's the part after the / in the sec line (e.g., A27DE0114241CAA6 in sec rsa4096/0xA27DE0114241CAA6 2023-03-15 [SC]).

3. Next, set up Git to use your GPG key by running:

git config --global user.signingkey <your_GPG_key_ID>

Replace <your_GPG_key_ID> with the key ID you noted down earlier.

4. Configure Git to sign all commits automatically:

To sign all your commits automatically, run:

git config --global commit.gpgsign true

Now, Git will use your GPG key to sign all commits by default.

Contributing to the project

Step 1: Fork the Repository

1. Navigate to the repository on git.vdm.dev.
2. Click the Fork button in the top-right corner of the repository page.

Step 2: Clone Your Forked Repository

In your terminal, run the following command to clone your forked repository to your local machine:

git clone ssh://git@git.vdm.dev:your-username/project-name.git

Replace your-username and project-name with your actual Git username and the name of the repository.

Example:

git clone ssh://git@git.vdm.dev/Llewellyn/Afrikaans-1933.git

Step 3: Change to the Repository Directory

Navigate to the cloned repository directory:

cd project-name

Replace project-name with the name of the repository.

Step 4: Create a New Branch

Create a new branch and switch to it. Replace feature-name with the name of the feature you're working on:

git checkout -b feature-name

Step 5: Make Commits

Make changes to the code and commit them:

git add .
git commit -am "Your commit message here"

Step 6: Push Your Branch

Push your branch to your forked repository:

To create the branch online and push the changes up

git push -u origin feature-name

if the branch already exists, to just push the changes up

git push origin feature-name

Replace feature-name with the name of the feature you're working on.

Step 7: Create a Pull Request

1. Navigate to your forked repository on git.vdm.dev.
2. Click the New Pull Request button.
3. Select the original repository as the base repository and your forked repository as the head repository.
4. Choose your feature-name branch as the compare branch.
5. Click Create Pull Request and fill in the necessary information.

Once you've completed these steps, the repository maintainer(s) will be notified of your pull request and can review your changes.

When the maintainer(s) merge your pull request, they normally will delete your feature-name branch on Gitea, you will now also delete this branch from your local repository.

6. Switch to the master branch in your local repository:

git checkout master

7. Delete the now merged feature branch:

git branch -d feature-name

Replace feature-name with the name of the feature that has now been merged.

Updating Your Local Branch After a Successful Merge

This guide assumes you have already successfully merged a pull request into the main repository.

Step 1: Make sure you are on the Master Branch

Switch to the master branch in your local repository:

git checkout master

Step 2: Add the Original Repository as a Remote

If you haven't already, add the original repository as a remote. Replace upstream with a name for the remote, and original-repo-url with the original repository's URL:

git remote add upstream original-repo-url

Example:

git remote add upstream ssh://git@git.vdm.dev/getBible/Afrikaans-1933.git

Step 3: Fetch Changes from the Original Repository

Fetch the changes from the original repository:

git fetch upstream

Step 4: Merge the Changes into Your Local Master Branch

Merge the changes from the original repository's master branch into your local master branch:

git merge upstream/master

Note: You can combine step 3 and 4 into one with:

git pull upstream master

Step 5: Push the Changes to Your Forked Repository

Push the updated master branch to your forked repository:

git push origin master

Now your local master branch and your forked repository's master branch are in sync with the original repository.

Adding more Changes to the Project

This guide assumes your local branch is in sync with the original repository, and you want to contribute another feature or change.

Note: If you have deleted the local repository folder, follow the steps from the "Contributing to a Project" guide. If your fork still exists online, start from step 2 of the "Contributing to a Project" guide, and then follow the steps in the "Updating Your Local Branch After a Successful Merge" guide to ensure everything is in sync before proceeding with the steps below.

Step 1: Make Sure You Are on the Master Branch

Switch to the master branch in your local repository:

git checkout master

Step 2: Create a New Branch for the New Feature

Create a new branch and switch to it. Replace new-feature-name with the name of the new feature you're working on:

git checkout -b new-feature-name

Step 3: Make Changes and Commits

Make changes to the code and commit them:

git add .
git commit -am "Your commit message here"

Step 4: Push Your Branch

Push your branch to your forked repository:

To create the branch online and push the changes up

git push -u origin feature-name

if the branch already exists, to just push the changes up

git push origin feature-name

Replace new-feature-name with the name of the new feature you're working on.

Note: You can repeat step 3 and 4 over and over until your feature is finished and ready to be merged into the original repository master branch, then continue to step 5. Communicate with the maintainer(s) of the original repository regarding the size and amount of changes they will allow in one Pull Request. This will help you know how many times you can repeat step 3 and 4 before moving on to step 5.

Step 5: Create a New Pull Request

Follow the steps in the "Contributing to a Project" guide to create a new pull request for your new feature or change.

Once you've completed these steps, the repository maintainer(s) will be notified of your new pull request and can review your changes.

This you will do over and over during your contribution to the project.