docs.selfprivacy.org/src/CONTRIBUTING.md

SelfPrivacy Project Contribution Guide

Contents

• Getting Started
  • Intended Audience
  • Requirements
  • Working with git
    • Registering on our Gitea instance
    • Forking
    • Cloning
    • Editing
    • Comitting changes
    • Reviewing
    • Making a pull request
• Contributing
  • SelfPrivacy webpage
    • Getting the repository
    • Repository structure
  • Application translations
    • Getting the repository
    • Repository structure

Getting Started

Welcome to the SelfPrivacy Project Contribution guide. This document is brought to you by SelfPrivacy team to help people willing to contribute into our project. This document contains quick explanation of everything you'll need to help the project growing, developing and improving.

Intended Audience

This document is divided into two parts and depending on your experience of working with a technical projects, you may be interested in reading both or just one of the parts.

If you have a basic understanding of git version control system and had previous experience of working with Gitea git server, then you'll probably be interested in skipping the first part as it contains the most basic concepts of git explained and illustrated using Gitea as an example.

In case if all(or some) of the mentioned things is relatively new to you - feel free to look into first part. It covers the minimal amount of the things that you'll need to get started.

Requirements

• Basic command shell(CLI) skills
• Git concepts understanding

Working with git

What git is

Git - is one of the most popular version control systems, used by millions of developers and libre/open source contributors all over the world.

This is very powerful tool that provides your files(mostly, your code) with change tracking, fault tolerance, versioning and work separation for teams and different environments. Such power is provided at a cost of implementing a couple of new concepts that needed to be understood before starting to work with git. Those concepts are not complicated so it's not a big challenge to understand them.

To tell long story short, git expects code to be stored on the remote server in the repository. You work with code by downloading(cloning) repository to your computer. When you make changes to your local copy of a repository, you give git a command to syncronize changes in your local copy of repository with remote one. When you syncronize your changes, git server(Gitea in our case) records each change you've done. If something goes wrong with your code, you can rollback to it previous version.

A few words about Gitea

As far as I mentioned, git expects you to store your code in the remote repository. For this reason the remote server required to store your code. You might have already heard about a couple. The most popular include:

• Github
• Gitlab
• Bitbucket

The problem of this services is that they are owned by big corporations like Microsoft or Atlassian, so it means that when they offer to hold your code for no cost, they use access to your private data as a fee for using their development in which they invest millions of dollars(it fully pays off itself, in fact).

As we are the project that fights to allow people to defend their privacy, we can't trust our code to those information-devouring companies. For this reason we chosen a git server that can be hosted on a self-hosted private server that server our developments for the sake of community. For us this server is Gitea. It can be accessed here.

Except repositories and cloning, concepts of git, you'll need to be acknowledged with are: commit and push.

Author commits changes to this article :)

Not to bore you completely with the theory, let's jump to the part where all of the fun begins,

Registering on our Gitea instance

1. First of all, go to the link, where our Gitea can be found: https://git.selfprivacy.org

2. You will be presented with the following picture:

You will need an upper right corner of this webpage:

3. Push a Register button

4. You will be presented with quite standard registration form:

5. Complete the registration. Do not forget to create a strong and memorable password.

6. After completing the registration, log into the Gitea.

My congratulations. You have successfully registered an account on Gitea

Forking

Remember, I mentioned a couple of new concepts that git introduces, right? Forking - is one of them. But before I explain what does it mean, let me briefly explain how to access existing repositories.

1. After successful registration and login you'll be presented with your repositories list, commit activity heatmap and a repository search:

2. Please use a search bar to search for repository that you want to contribute:

3. When you search for the repository, found ones will appear as a search result. Click on the one, you want to contribute to.

SelfPrivacy webpage repository page

Now, let's go back to forking. When you want to make some changes to the sources in the repository, you can't commit changes to the original one directly, unless you're granted permission to. Usually, the only people that have permission to directly modify the repository, are the core development team. For all the contributors there's different apprach exist.

Contributors can modify the original repository by creating an identical copy of it on their own account, making changes to it and requesting moderators to overwrite(or merge) files with changed ones. Moderator reviews changes before approving them, gives some comments regarding the changes and if everything is OK, then he/she accepts proposed changes.

Forking - Creating an identical copy of a repository on your own account of a git server

To fork a git repository, you'll have to push a Fork button(can be found at the upper right corner of the repository interface):

When you'll fork the repository, the identical one will appear in your account and you'll be able to make modifications to it.

Cloning

Remember, I said that wheen you're working with a code inside of a git repository, to make some changes, you'll firstly have to clone it to your computer, right?

Now it's time for me to show you how to begin making changes to your code.

To clone a repository, you'll have to use a CLI git utility. let's begin with opening your terminal:

Microsoft Windows users would have to open a "PowerShell" application. Mac users will be able to find a "Terminal" app in the "Utilities" folder.

First of all, you'll have to pick a location where you would like to store the repository with a code. It can be specially created, deticated folder, or just your home directory

For our example let's pick home directory as the folder to which we'll clone our repository(home folder opened by default by the most shells).

Let's clone a webpage repository to our computer. To do so, please run the following command:

git clone https://git.selfprivacy.org/ilchub/selfprivacy-frontend

If you'll now open the file manager, you'll see the newly cloned repository(which is now just a folder on our disk :)

From this point we can start editing project files

Editing

Editing of a project is a subject of quite personal taste. From the point of getting the code to your computer, it's totally up to you, what code editor to choose. Author used (Neo)Vim and VS Code to write the following article.

Author, writing article in the VS Code

Feel free to explore the repository and edit it in a way you want.

Commiting

After you've made all desired changes, time comes to push your changes to the Gitea server to store them in a safe place and keep track of them. In the world of git, making changes to the source code is described by pretty self-explainable word - commiting. To commit changes to the code, we'll again need to use some CLI skills.

Open your terminal and make sure that you're currently in the same directory that code resides in. Your current directory can be determined by running the following command:

pwd

and it defaults to your home folder:

In case if you're not in the same directory with your code, you can change by running the following command:

cd /path/to/the/directory/with/my/code

After that you can again rerun pwd to make sure that directory is correct.

When the requirement of being in the correct directory is met, you can start commiting your changes.

First of all, please run the following command:

git add .

This command will result in git searching recursively through the entire directory for changes you've made in the files:

This command will produce no output so don't be worried by that fact.

After searching for changes, your next step will be to add them to the queue for syncronization with the Gitea server. To do so, please run the following:

git commit -m "Brief explanation of changes"

This command will output all changes that were made to the folder(of course in case if you defined a correct search scope with git add command).

That's the point when all your changes are indexed and queued for being pushed to the remote server. To push changes to the remote server, please run:

git push -u origin master

My congratulations. Your changes have been successfully written ton the remote repository. You can wisit Gitea to check them. You should now see your fresh changes.

Reviewing

Right after pushing your changes to the remote repository, it's rather good idea to review them. If you'll visit your repository, you'll see that the last commit on the page have changed:

You can click the "Commits" button to see the history of all your commits:

If you'll click onto one of the commits, you will be able to see what things changed since last push:

Gitea will show you the detailed explanation on what have been added to your code and what have been removed.

That's how changes review works.

Note: You can add comments to each line by clicking on it.

Contributing

SelfPrivacy Webpage

Repository URL

https://git.selfprivacy.org/ilchub/selfprivacy-frontend

Application translations

Repository URL

https://git.selfprivacy.org/kherel/selfprivacy.org.app