kemonine
/
lollipopcloud
Archived
1
0
Fork 0
Code Releases Activity

Merge branch 'howtogitea' of jmf/lollipop-docs into master

This commit is contained in:
jmf 2018-07-20 23:21:52 +00:00 committed by Gitea
parent 771917dff7 3220e34e03
commit 7fd4bfbcb9
1 changed files with 41 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
how-to-gitea.md
View File

@ -1,62 +1,74 @@
# You don't have to learn git or Gitea to contribute...
If you would like to walk through the git contribution process to submit changes, skip this section and move down to the [cheatsheat](#"Gitea cheat sheet for beginners and the forgetful"). But if you have no interest in expending that much energy, we don't blame you. You can skip git entirely and submit a detailed suggestion in the form of a ticket (or "issue," in git-speak).
You will need to [create an account here (link)](https://git.lollipop.holdmybeer.solutions/user/sign_up) and then log in, if you have not already.
Open the specific [Lollipop Repository (such as lolipop_lan_cloud, website, or docs) (link)](https://git.lollipop.holdmybeer.solutions/) you would like to improve. Then click on the "issues" tab.
It is good practice to use the search box to search existing issues (with a keyword or two) ensure you're not making a suggestion that's already been made-- and if your suggestion has already been made, we would love if you would add your thoughts and comments to the existing ticket. The more information we have, the easier it will be to implement the request (as long as it is technically feasible). This also helps us understand how popular a request is, and helps us prioritize our updates.
If the issue does not exist already, select the "new issue" button, and provide as much information as you are able. Be sure to include a descriptive title! When you're ready, click "create issue" and leave the rest to us.
If you would like to walk through the git contribution process to submit changes, skip this section and move down to the [cheatsheat](#"Gitea cheat sheet for beginners and the forgetful"). But if you have no interest in expending that much energy, you can skip git entirely and submit a detailed suggestion to our [kanban board (link)](https://kanban.lollipopcloud.solutions/).
# Gitea cheat sheet for beginners and the forgetful
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](#Bibliography) at the end, if you want to dive deeper. You may even want to skip this document entirely at first, and try [Your First Pull Request (link)](https://joshuahunter.com/posts/your-first-pull-request/) more suited to your needs.
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](#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 (link)](https://joshuahunter.com/posts/your-first-pull-request/) more suited to your needs.
If you just can't get enough Git (perhaps because you are a glutton for punishment), check out the [Git Book (link)](https://git-scm.com/book/en/v2).
If you need more Git, check out the [Git Book (link)](https://git-scm.com/book/en/v2).
# Basic Steps For Contributing
These are the general steps, but if you need more information, keep reading.
* Fork the repository (just once!) from [Lollipop Cloud project page (link)](https://git.lollipop.holdmybeer.solutions/)
* Clone your fork on your own computer
* Fork the repository (just once) from [Lollipop Cloud project page (link)](https://git.lollipopcloud.solutions/)
* Clone your fork on your own computer (just once)
* Create a branch for your changes
* Edit, make changes and contributions
* Push those changes to your fork
* Push those changes to your branch
* Open a merge/pull request in Gitea
* Wait for project coordinator to provide feedback or approve the merge/pull request
# And now... what to do if you've never done this before
### Log in to Gitea
If you haven't already, create an account on the [Lollipop Cloud project page (link)](https://git.lollipop.holdmybeer.solutions/) and log in.
If you haven't already, create an account on the [Lollipop Cloud project page (link)](https://git.lollipopcloud.solutions/) and log in.
### Fork it! (copy the project to your Gitea account)
View the repository you would like to work on (code, docs, website), and click `Fork` in the upper right corner. You will only have to fork once!
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 (link)](https://putty.org/) for Windows users, or the built-in Terminal for MacOS users.
### Create a directory (an empty folder) for where you'd like your copy of the project to live, and open it.
### Go to (or create) a directory where you'd like your copy of the project to live, and open it.
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.
`mkdir /path/to/lollipop_project`
`cd /path/to/lollipop_project`
### CLONE (create a local copy) of the project files
### Clone (create a local copy) of the project files
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.lollipop.holdmybeer.solutions/your-username/forked-repository`, with the correct URL.
You are downloading all the project files to your computer! Yay!
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!
### View your cloned project on your computer
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.
### Edit your contributions!
Now that the files live locally on your computer, you can edit them with your favorite editor. Stick with the command line (Vim, Emacs, Nano), or use a text editor like [Atom (link)](https://atom.io/). Be sure to save your changes!
### Add the upstream path (Do this step only once!)
If the master (where you forked FROM) changes, you will have to update your local clone. You will only have to do this step ONE time!
From your `cloned_directory_name` directory, do this:
`git remote add upstream https://git.lollipopcloud.soltuions/lollipop_cloud/original_repository.git` (with the original repository URL).
### Create a branch
The `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 `new_branch_name`.
### Edit your contributions
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 (link)](https://atom.io/). Be sure to save your changes.
### Add your changed files to git, to prepare them for uploading
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.
@ -65,15 +77,15 @@ If you added new files to the project, in your terminal you will have to `git ad
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"`
### Push your changes to your fork
### Push your changes to the branch in your fork
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 origin master`
`git push -u origin new_branch_name`
### Create a pull request (AKA merge request)
Go back to your browser and your forked repository `https://git.lollipop.holdmybeer.solutions/your-username/forked-repository` and go to Pull Requests and choose `New Pull Request`.
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`. (As you get more advanced, you can create branches to compare. For our purposes, just select the two available branches that are probably named `master`. The "base" fork is the original project, NOT your forked version.) 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.
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.
## Congratulations! You've submitted your first pull request! 🎉
@ -84,22 +96,12 @@ The developers will review your changes and work with you on next steps.
## What to do when "upstream" changes...
"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.
### Add the upstream path (Do this step only once!)
If the master (where you forked FROM) changes, you will have to update your local clone. You will only have to do this step ONE time!
From your `/path/to/lollipop_project/new_clone_directory/` directory,
Do this: `git remote add upstream https://git.project-domain.com/forked_from/original_repository.git` with the original repository URL.
### Fetch the changes since you first forked or last fetched changes
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 `upstream/master`.
Make your edits!
### Merge your changes with the upstream repo (the original repo that you forked).
`git merge upstream/master`
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).
# Bibliography
@ -112,4 +114,5 @@ Make your edits!
* [Oh shit, git! (link)](http://ohshitgit.com/): how to fix a few Git mistakes (we all make them!)
* [PuTTY SSH and telnet client (link)](https://putty.org/)
* [Syncing a fork (link)](https://help.github.com/articles/syncing-a-fork/)
* [Vim Cheat Sheet (link)](http://vimsheet.com/)
* [Your First Pull Request (link)](https://joshuahunter.com/posts/your-first-pull-request/)