Below is the basic Gitea workflow, to help you with your contributions. But do not hesitate to reach out to any of the organizers for help! We’re happy to walk you through any or all of this, no matter what your experience level. If you’ve never even heard of Gitea before, we’d love to help you submit your first contribution!
This document gets wordy because Git is not as welcoming to beginners as we wish it was, but you can do it! And you’re not alone! We are just a message or comment away. There are even more resources in the Bibliography at the end, if you want to dive deeper. You may even want to skip this document entirely at first, and see if Your First Pull Request more suited to your needs.
If you need more Git, check out the Git Book.
These are the general steps, but if you need more information, keep reading.
If you haven’t already, create an account on the Lollipop Cloud project page and log in.
View the repository you would like to work on (docs or website), and click
Fork in the upper right corner. You will only have to fork once!
A fork is an exact copy of the project as it existed at the exact moment you forked it. So when the project updates in the future, you will have to update your code too, but we will talk about that later.
At this point, you will need a command line client like PuTTY for Windows users, or the built-in Terminal for MacOS users.
In PuTTY or Terminal, enter each of the following commands, where “lollipop_project” is the name of directory where you would like to store the clone.
View your newly created fork in your web browser and copy the https:// address in the box on the right side of the page.
In your terminal program, enter
git clone https://git.lollipopcloud.solutions/your-username/forked-repository, with the correct URL.
You are downloading all the project files to your computer! Good work!
Git will install the project in a new folder. Use the command
ls to see the name of the new project folder if you are unsure. Open this new folder with
cd cloned_directory_name to see what was installed.
(Do this step only once!)
Over time, you will want to keep your local clone of your fork updated with changes made to the original repo. To make this easier, define a “remote” repository in your local clone, called upstream, that points to the original repo.
cloned_directory_name directory, do this:
git remote add upstream https://git.lollipopcloud.solutions/lollipop-cloud/original_repository.git (with the original repository URL).
git checkout command at the end will create a branch, but this is a good practice for each time you want to create a new branch for contributing:
git checkout master
git fetch upstream
git rebase upstream/master
git checkout -b new_branch_name
Now the changes you make will be associated with
Now that the files live locally on your computer, and you have a branch set up for your new contributions, you can edit the files with your favorite editor. Stick with the command line (Vim, Emacs, Nano), or use a text editor like Atom. Be sure to save your changes.
If you added new files to the project, in your terminal you will have to
git add edited-file-name for each of those new files.
When you’re ready, go back to the command line and commit your changes with a short but descriptive comment.
git commit -m "Updated List of Anthropomorphic Potatoes"
When you’re really ready, “push” those changes to the original source, which is a request to accept and merge your contributions with the rest of the project. Note: A push request and a merge request are the same thing.
git push -u origin new_branch_name
Go back to your browser and your forked repository
https://git.lollipopcloud.solutions/your-username/forked-repository and go to Pull Requests and choose
New Pull Request.
There will be two drop-down menus that will probably say
base: master and
compare: master. The “base” fork is the original project, NOT your forked version. Under the
compare menu, choose your
new_branch_name. Enter a short title for the changes, a description to help reviewers understand your contributions, and click the big
Submit Pull Request button below your text.
The developers will review your changes and work with you on next steps.
“Upstream” is the name of the original code (not your fork). When it gets updated after you clone or fork, you will have to request a copy of those changes to stay up-to-date.
In order to be sure you’re working off the latest copy of the project, you can fetch the latest changes with
git fetch upstream. (Note: this can only be done at the command line, not the user interface/URL.)
Now you have the latest copy of the project in your local directory. Your new changes from this point forward will be stored in a local branch called
Make your edits! Then you can go back to the section [about adding your changed files to git](#Add your changed files to git, to prepare them for uploading).