Differences

This shows you the differences between two versions of the page.

--- contributing-to-batocera [2021/11/01 09:18] – better phrasing, reordering of some sections to be more logical atari
+++ contributing-to-batocera [2022/01/30 04:26] (current) – [Making changes in the future] a bit less contradictory phrasing atari
@@ Line 11: / Line 11: @@
 ===== Basics =====
-Batocera is an open-source software, its source code is hosted at [[https://github.com/batocera-linux/batocera.linux|https://github.com/batocera-linux/batocera.linux]]. In order to contribute to the point, you must make a pull request to this online repository (a "remote"). You can achieve this by installing a source control manager (the most obvious one being [[https://git-scm.com/downloads|git]]), make the changes on your locally and then make a pull request to Batocera's remote (from here on, we will refer to Batocera's remote as "upstream").
+Batocera is an open-source software, its source code is hosted at [[https://github.com/batocera-linux/batocera.linux|https://github.com/batocera-linux/batocera.linux]]. In order to contribute to the project, you must make a pull request to this online repository (a "remote"). You can achieve this by installing a source control manager (the most obvious one being [[https://git-scm.com/downloads|git]]), make the changes on your local clone and then make a pull request to Batocera's remote (from here on, we will refer to Batocera's remote as "upstream").
 This article mainly pertains to Linux distributions, but this should also be possible with Git Bash on Windows (with some workarounds, read below).
+<WRAP center round tip>
+Github also has a [[:github-desktop|desktop GUI]] for this, which may be more friendlier to those new to Github and source code editing in general.
+</WRAP>
 ===== Making your first pull request =====
@@ Line 22: / Line 26: @@
   - [[#clone_your_fork_locally|Clone your fork locally]]
   - [[#create_a_local_branch_on_your_fork|Create a new local branch on your fork]]
-  - [[#making_and_testing_the_modifications|Make the modifications locally]]
+  - [[#making_and_testing_the_modifications|Make (and possibly test, if only minor changes) the modifications locally]]
   - Build Batocera and test the modifications, fixing any issues that arise
-  - [[#push_your_commits_to_the_new_branch|Push your commits to the new branch]]
+  - [[#commit_changes_to_the_local_branch|Push your commits to the new branch]]
-  - Make a pull request to batocera.linux containing those commits
+  - [[#create_the_pull_request|Make a pull request to batocera.linux containing those commits]]
-Initial setup involves a few extra steps, but once setup creating future pull requests are much easier. All you have to do is make sure your local repository is up to date with upstream.
+Initial setup involves a few extra steps, but once complete, creating future pull requests are much easier. All you have to do is make sure your local repository is up to date with upstream.
-<WRAP center round tip>
-Github also has a [[https://desktop.github.com/|desktop GUI]] for this, however instructions for this client cannot be provided (yet). If you choose to go down this route, hopefully the GUI is intuitive enough to work out what the equivalent actions on it are.
-</WRAP>
 ==== Fork Batocera to your own repository ====
@@ Line 61: / Line 61: @@
 Other distros generally use more recent versions so this isn't as important.
+<WRAP center round tip>
+''gh'' can be used to store login credentials. This package may also be known as ''github-cli'' on your distribution.
+Once installed, run ''gh auth login'' and answer the following like so:
+<code>
+What account do you want to login to? Github.com
+What is your preferred protocol for Git operation? HTTPS
+Authenticate Git with your Github credentials? Yes
+How would you like to authenticate Github CLI? Login with a web browser
+</code>
+Then follow its instructions. If a web browser is not available for authentication, [[https://github.com/settings/tokens|personal access tokens]] can be used instead.
+</WRAP>
 === Windows ===
@@ Line 67: / Line 82: @@
 <WRAP center round info>
-You'll note that this program also offers "Git GUI". If you use this, just like with Github Desktop, you're on your own.
+You'll note that this program also offers "Git GUI". If you use this, you're on your own.
 </WRAP>
@@ Line 86: / Line 101: @@
 It is important to distinguish between remote and local repositories. Right now, your account has a remote repository that is a fork (copy) of Batocera.linux. We need to clone (download) this origin remote repository to your local computer to be able to make local edits to it.
-The easiest way is to open a command line, navigate to the directory you would like to save the origin repository to and run ''%%git clone https://github.com/<your Github username>/batocera.linux%%''.
+The easiest way is to open a command line, navigate to the directory you would like to save the origin repository to and run:
+<code bash>
+git clone https://github.com/<your Github username>/batocera.linux
+</code>
 Once done (this may take a while, depending on your internet speed), run the following:
-  * ''cd batocera.linux''
-  * ''%%git remote add upstream https://github.com/batocera-linux/batocera.linux.git%%''
+<code bash>
-  * ''%%git remote set-url upstream https://github.com/batocera-linux/batocera.linux.git%%''
+cd batocera.linux
-  * ''%%git remote set-url origin https://github.com/YOURNAME/batocera.linux%%'' where ''YOURNAME'' is your Github username.
+git remote add upstream https://github.com/batocera-linux/batocera.linux.git
+git remote set-url upstream https://github.com/batocera-linux/batocera.linux.git
+git remote set-url origin https://github.com/<your Github username>/batocera.linux
+</code>
+where ''<your Github username>'' is your Github username (remove the "<>" characters).
 This will config the local repository to be recognized as a fork of upstream (the original remote repository). This makes it easier to stay "in sync" with future changes made to upstream.
+Submodules (such as buildroot) will become outdated over time. Run the following to set them up to update along with the main repository:
+<code bash>
+git submodule init
+git submodule update
+</code>
 ==== Create a local branch on your fork ====
@@ Line 100: / Line 131: @@
 The ''master'' branch is the "main" branch on which Batocera is built from. If you start making changes directly on your local master branch and make a pull request using that, any additional changes made after the fact **will be added to that very pull request**, preventing you from making additional changes until that pull request has been merged by upstream. Instead, it is advisable to create a new local branch based on the master branch for each set of changes you want to make per pull request, as that will allow you to make more than one pull request at a time.
-To create a new local branch, run ''git checkout -b name-of-the-branch''. Then you can run ''git commit'' when you have completed your changes.
+To create a new local branch, run ''git checkout -b name-of-the-branch''.
 <WRAP center round info>
@@ Line 112: / Line 143: @@
 ==== Making and testing the modifications ====
-You have some guidelines on [[:batocera.linux_buildroot_modifications|this page to compile individual packages]], a [[:notable_files|list of notable files and their location on a live install]] and [[:compile_batocera.linux|this page for more general compilation of the whole Batocera Linux system]].
+You have some guidelines:
+  * [[:coding_rules|The coding rules page for adding new scripts]]
+  * [[:notable_files|A list of notable files and their location on a live install]]
+  * [[:batocera.linux_buildroot_modifications|Compiling individual packages]]
+  * [[:compile_batocera.linux|The compiling Batocera page for more general compilation of the whole Batocera Linux system]]
-==== Push your commits to the new branch ====
+==== Commit changes to the local branch ====
-Once your changes have been tested and you're ready to make a pull request, merge your commit (changes to files) using ''%%git push --set-upstream origin name-of-the-branch%%''. This will "push" your changes to the origin remote. You can double check that this has occurred by visiting your appropriate branch on your fork at https://github.com/YOURNAME/batocera.linux
+After creating, testing and finalizing your changes, run ''git commit -a'' to commit them to the branch. Git will ask you to provide a short description of your changes, this should be no longer than a single sentence. If the changes are more involved and require a deeper description, create the "header" summary on the first line and insert a blank space followed by the longer description.
-Once you've confirmed that you have successfully pushed your changes to your own origin remote, go to the produced link in the output of the command and click on ''Pull Request''. This will let you ask to merge the changes into the main repository.
+If additional changes need to be made after the fact, run ''git commit -a'' again to add another commit. If many commits have been added to the branch, consider squashing the commits into one.
+==== Create the Pull Request ====
+When all the commits have been committed, merge the commits from your local clone into your fork's repository with the following command (replacing the name of the branch with your own):
+<code bash>
+git push --set-upstream origin name-of-the-branch
+</code>
+<WRAP center round info>
+The first time doing this you will be asked to setup your current Git profile. Enter your Github account's e-mail and username using the provided commands as appropriate and try again.
+</WRAP>
+This will "push" your changes into your fork. You can double check that this has occurred by visiting your appropriate branch on your fork at https://github.com/YOURNAME/batocera.linux
+Once you've confirmed that you have successfully pushed your changes to your own origin remote, click the **Contribute** button near the top of the page to submit the pull request to Batocera's main repository.
+<WRAP center round tip>
+If using Git Bash, a prompt with the appropriate URL will be presented to you once the push is complete. Click that instead to immediately go to the correct page.
+</WRAP>
+==== Using gh to create Pull Requests ====
+If you opted to install ''gh'' to manage your credentials, it too can be used to create new pull requests instead of the web interface. Run ''gh pr create'' and set the base repository to ''batocera-linux/batocera.linux''. Submitting the changes in the browser is recommended as it shows all the accumulated changes on the same page before the actual submission.
 ===== Making changes in the future =====
@@ Line 126: / Line 185: @@
   - ''%%git fetch upstream%%'' : Tells git to grab every changes from the upstream repository
   - ''%%git rebase upstream/master%%'' : Tells git to make your branch up to date with the master branch of the upstream repository
+  - (Optional) ''%%git push%%'' : Pushes the latest commits to **your fork's** remote repository.
-<WRAP center round info>
+<WRAP center round tip>
-It is not recommended to use ''%%git pull upstream master%%''. [[https://longair.net/blog/2009/04/16/git-fetch-and-merge/|Here's a good blog post about it.]]
+You can create an alias for these commands by executing the following:
+<code bash>
+git config --global alias.update '!git checkout master && git fetch upstream && git rebase upstream/master && git push'
+</code>
+This way, running ''git update'' will execute all the commands required to sync up your local and remote master branch with batocera.linux's master branch.
 </WRAP>
 Then repeat the steps from the [[#create_a_local_branch_on_your_fork|"Create a new local branch on your fork"]] section above.
+<WRAP center round info>
+Performing fetches and merges manually instead of relying on aliases can be quite powerful. [[https://longair.net/blog/2009/04/16/git-fetch-and-merge/|Here's a good blog post about it.]]
+</WRAP>
+<WRAP center round tip>
+As you create new changes and successfully complete PRs, branches can start piling up on your cloned fork.
+You can remove old branches from your cloned repository by first switching to the appropriate branch (''git checkout name-of-branch'' if not already on it) and then running ''git branch -d'' when you are done with them and the pull request has since been closed.
+</WRAP>
+===== Tips =====
+==== Check all the current differences ====
+This will just show the differences in the files between now and the last commit. This is not a reflection of all the differences between the branch and the master branch.
+<code bash>
+git diff
+</code>
+==== Discard all changes ====
+This restores files back from the last commit. First, ensure you are on the branch you intend to undo the changes on, and run the following:
+<code bash>
+git restore .
+</code>
+Individual files can also be specified by replacing ''.''.
+===== Troubleshooting =====
+==== There are changes to the buildroot submodule that I didn't make! ====
+That's why you updated the submodules earlier. But this can also happen if you say download a branch from the remote that hasn't had the submodules updated yet. To update the submodules again run the following:
+<code bash>
+git submodule update
+</code>