Skip to content

Revise lifecycle of a patch chapter #235 #247

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Revise lifecycle of a patch chapter #235 #247

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d655989
Main
Siddd-hrr Oct 6, 2025
1356caa
Third commit
Siddd-hrr Oct 6, 2025
486f05b
Fourth Commit
Siddd-hrr Oct 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 38 additions & 37 deletions chapters/lifecycle_of_a_patch.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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/<pull_request_number>.diff`
`https://patch-diff.githubusercontent.com/raw/r-devel/r-svn/pull/<pull_request_number>.diff`

Save `<pull_request_number>.diff` as a plain text file to [submit your patch](#SubmitPatches), remember to check if it meets the [recommendations for good patches](#GoodPatches).
Save `<pull_request_number>.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}

Expand Down