diff --git a/chapters/lifecycle_of_a_patch.qmd b/chapters/lifecycle_of_a_patch.qmd index 0d9eab4..3be77e2 100644 --- a/chapters/lifecycle_of_a_patch.qmd +++ b/chapters/lifecycle_of_a_patch.qmd @@ -10,7 +10,7 @@ There might be a situation where you come across a bug in R, which you may have When you submit a patch, you are helping the developer(s) and maintainer(s) so that they do not have to write the entire code from scratch. Instead, they can test and tweak your patch, if necessary. -## What tools are required to submit a patch? +## Preparing a patch from the SVN repository To submit a patch, you need: @@ -28,71 +28,72 @@ To submit a patch, you need: Depending on the operative system you might need to do some steps before that. The different steps required can be found in previous chapters of the book, for [Windows](#windows), [macOS](#macos) and [Linux](#linux). -## How to prepare a patch? +## Preparing a patch using the Github mirror +### How to prepare a patch? -If you have the source code in `$TOP_SRCDIR` you can edit the files, for example a documentation file such as `"$TOP_SRCDIR"/src/library/stats/man/Multinom.Rd`, to make your desired changes to that or more files. + If you have the source code in `$TOP_SRCDIR` you can edit the files, for example a documentation file such as `"$TOP_SRCDIR"/src/library/stats/man/Multinom.Rd`, to make your desired changes to that or more files. -Then you should check that R still works as expected via: + Then you should check that R still works as expected via: - ```sh - cd "$TOP_SRCDIR" - make check-devel - ``` + ```sh + cd "$TOP_SRCDIR" + make check-devel + ``` -If there is no test for your proposed change you can add a new regression test, following [the guidelines](#sec-testing-pre-releases). + If there is no test for your proposed change you can add a new regression test, following [the guidelines](#sec-testing-pre-releases). -Then you should bring changes from the repository into the working copy, in case any other change has been introduced, and create a patch.diff file with just the changes you want to propose to the R core: + Then you should bring changes from the repository into the working copy, in case any other change has been introduced, and create a patch.diff file with just the changes you want to propose to the R core: - ```sh - svn update - svn diff > patch.diff - ``` - -Most often, changes are made to existing files, but if you happen to be adding a new file in your change, you'll need to run `svn add path/to/file1 ...` before running `svn diff` to mark those files for inclusion. + ```sh + svn update + svn diff > patch.diff + ``` + + Most often, changes are made to existing files, but if you happen to be adding a new file in your change, you'll need to run `svn add path/to/file1 ...` before running `svn diff` to mark those files for inclusion. -This `patch.diff` file is the one that can be proposed to the R core via [Bugzilla](#SubmitPatches). You can also [ask for reviews](#PatchesReview) to the patch before proposing it to the R core via the [r-devel mailing list](https://stat.ethz.ch/mailman/listinfo/r-devel) or the slack channel of the R-contributors space. + This `patch.diff` file is the one that can be proposed to the R core via [Bugzilla](#SubmitPatches). You can also [ask for reviews](#PatchesReview) to the patch before proposing it to the R core via the [r-devel mailing list](https://stat.ethz.ch/mailman/listinfo/r-devel) or the slack channel of the R-contributors space. ### Using a git mirror -Besides checking in your computer, you can use the Github mirror [r-devel/r-svn](https://github.com/r-devel/r-svn "A github svn mirror") of the source code to check this patch with different configurations and OS. + Besides checking in your computer, you can use the Github mirror [r-devel/r-svn](https://github.com/r-devel/r-svn "A github svn mirror") of the source code to check this patch with different configurations and OS. -You should first find the file to edit, via the github interface for example: + You should first find the file to edit, via the github interface for example: -![Screenshot of the heading of the src/library/stats/man/Mulinom.Rd](../img/rsvn_file_to_edit.png "Opening the file to edit.") + ![Screenshot of the heading of the src/library/stats/man/Mulinom.Rd](../img/rsvn_file_to_edit.png "Opening the file to edit.") -Then you can edit it, directly in the interface or using the github interface: + Then you can edit it, directly in the interface or using the github interface: -![Screenshot of the file src/library/stats/man/Mulinom.Rd being edited via the Github interface](../img/rsvn_edit_file.png "Editing a file via Github interface.") + ![Screenshot of the file src/library/stats/man/Mulinom.Rd being edited via the Github interface](../img/rsvn_edit_file.png "Editing a file via Github interface.") -Create a commit with a message describing the changes + Create a commit with a message describing the changes -![Screenshot of the commit message](../img/rsvn_commit_message.png "Commiting the change in the file.") + ![Screenshot of the commit message](../img/rsvn_commit_message.png "Commiting the change in the file.") -And create a pull request from the branch created to check the changes. + And create a pull request from the branch created to check the changes. -![Screenshot of the message when opening a pull requests from the branch](../img/rsvn_commit_pre_PR.png "Starting a pull requests with the changes previously committed.") + ![Screenshot of the message when opening a pull requests from the branch](../img/rsvn_commit_pre_PR.png "Starting a pull requests with the changes previously committed.") -Add a message and description of the svn for other users and the R core to know what is the purpose of this modification: + Add a message and description of the svn for other users and the R core to know what is the purpose of this modification: -![Screenshot of the message and content while opening a pull requests for the r-svn repository](../img/rsvn_PR_message.png "Describe the changes in the pull request.") + ![Screenshot of the message and content while opening a pull requests for the r-svn repository](../img/rsvn_PR_message.png "Describe the changes in the pull request.") -![Screenshot of the pull requests opened](../img/rsvn_PR_created.png "The result of opening a pull requests with the changes.") + ![Screenshot of the pull requests opened](../img/rsvn_PR_created.png "The result of opening a pull requests with the changes.") -Once the PR is submitted, some automatic checks will be triggered (they might need to be approved by some other users as per Github rules): + Once the PR is submitted, some automatic checks will be triggered (they might need to be approved by some other users as per Github rules): -![Screenshot of the checks triggered by opening the pull request](../img/rsvn_PR_automatic_checks.png "Automatic checks triggered in the r-devel/r-svn github repository.") -When the checks end you will need to explore the results and asses if the results indicate a problem or not. + ![Screenshot of the checks triggered by opening the pull request](../img/rsvn_PR_automatic_checks.png "Automatic checks triggered in the r-devel/r-svn github repository.") + When the checks end you will need to explore the results and asses if the results indicate a problem or not. -![Screenshot of the results of the Github checks in the r-svn mirror](../img/rsvn_checks_results.png "Summary of the results of the automatic checks triggered by opening the pull request.") + ![Screenshot of the results of the Github checks in the r-svn mirror](../img/rsvn_checks_results.png "Summary of the results of the automatic checks triggered by opening the pull request.") -Once you are happy with the changes and the checks report that everything is okay you can retrieve the patch via: + Once you are happy with the changes and the checks report that everything is okay you can retrieve the patch via: -`https://patch-diff.githubusercontent.com/raw/r-devel/r-svn/pull/.diff` + `https://patch-diff.githubusercontent.com/raw/r-devel/r-svn/pull/.diff` -Save `.diff` as a plain text file to [submit your patch](#SubmitPatches), remember to check if it meets the [recommendations for good patches](#GoodPatches). + Save `.diff` as a plain text file to [submit your patch](#SubmitPatches), remember to check if it meets the [recommendations for good patches](#GoodPatches). -If you want to use `git` from the terminal to create the pull request (PR) to test the changes, you can use this [summary of the available git commands](https://about.gitlab.com/images/press/git-cheat-sheet.pdf "git cheat sheet"). + If you want to use `git` from the terminal to create the pull request (PR) to test the changes, you can use this [summary of the available git commands](https://about.gitlab.com/images/press/git-cheat-sheet.pdf "git cheat sheet"). ## Making good patches {#GoodPatches}