Skip to content

Commit

Permalink
Adjust submission procedure documentation to get correct PR base repo
Browse files Browse the repository at this point in the history
The goal is to make it possible for any community member to submit libraries to the registry, regardless of their level
of relevant technical expertise. For this reason, the project documentation includes a detailed and comprehensive set of
instructions for submitting a library.

Since the time these instructions were written, a regression was introduced into the GitHub website:

When creating a commit via the GitHub web interface, the dialog allows the user to select which branch the commit should
be made to. Typically this includes two options:

- "Commit directly to the <target branch> branch"
  (where "<target branch>" is the branch the user had selected when they initiated the procedure)
- "Create a new branch for this commit and start a pull request"

If the branch protection rules configured for the target prevent the user from committing to that branch, then the first
of the options is removed (which is the appropriate behavior).

Following GitHub's regression, under the conditions produced by the previous submission procedure, the determination of
whether the first option should be disabled is based on the branch protection configuration of the
arduino/arduino-registry repository, not of the library submitter's fork. This is incorrect because the fork does not
inherit the branch protection settings of the parent, meaning the target branch will never be protected in the fork and
thus that the commit to that branch should be allowed in the dialog.

Because we do have branch protection rules enabled for the `main` branch of the `arduino/library-registry` repo, this
bug causes the default setting in the dialog to be changed from "Commit directly to the main branch" to
"Create a new branch for this commit and start a pull request" when the documented submission procedure is performed.

Strangely, the user flow is significantly different depending on which of these options is selected. The user flow when
"Create a new branch for this commit and start a pull request" is selected forces the user to submit the PR to their own
fork repository instead of to arduino/library-registry. It is essential for the PR to be submitted to
arduino/library-registry so this change in the outcome of the previous documented submission procedure as a side effect
of GitHub's regression is catastrophic.

The submission instructions are hereby updated to once again produce a correct submission. Unfortunately, the procedure
that is now required is more complex and less intuitive than the previous one. In order to mitigate this, I made an
effort to be extra explicit both in describing the actions to be performed, as well as describing the expected result of
each action.

I reported the regression to GitHub. I will change the documentation back to using the more friendly submission
procedure once it is fixed.
  • Loading branch information
per1234 committed Aug 22, 2023
1 parent 42394c2 commit 19ab8cf
Showing 1 changed file with 26 additions and 5 deletions.
31 changes: 26 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,13 +35,34 @@ See the instructions below for detailed instructions on how to do this via the G
1. You may want to first take a look at
[the requirements for admission into the Arduino Library Manager index](FAQ.md#submission-requirements). Each submission will be checked for
compliance before being accepted.
1. Open this link to fork this repository and edit the list via the
GitHub web interface: https://github.com/arduino/library-registry/edit/main/repositories.txt
1. Click the <kbd>Fork this repository</kbd> button.
1. Click the following link:<br />
https://github.com/arduino/library-registry/fork<br />
The "**Create a new fork**" page will open.
1. Click the <kbd>Create fork</kbd> button in the "**Create a new fork**" page.<br />
A "**Forking arduino/library-registry**" page will open while the fork is in the process of being created.
1. Wait for the "Forking" process to finish.<br />
The home page of your [fork](https://docs.github.com/get-started/quickstart/fork-a-repo) of the **library-registry** repository will open.
1. Click on the file `repositories.txt` under the list of files you see in that page.<br />
The "**library-registry/repositories.txt**" page will open.
1. Click the pencil icon ("Edit this file") at the right side of the toolbar in the "**library-registry/repositories.txt**" page.<br />
The `repositories.txt` file will open in the online text editor.
1. Add the library repository's URL to the list (it doesn't matter where in the list). This should be the URL of the repository home page. For example:
`https://github.com/arduino-libraries/Servo`
1. Click the <kbd>Propose changes</kbd> button.
1. In the **"Comparing changes"** window that opens, click the <kbd>Create pull request</kbd> button.
1. Click the <kbd>Commit changes...</kbd> button located near the top right corner of the page.<br />
The "**Commit changes**" dialog will open.
1. Click the <kbd>Commit changes</kbd> button in the "**Commit changes**" dialog.<br />
The "**library-registry/repositories.txt**" page will open.
1. Click the "**library-registry**" link at the top of the "**library-registry/repositories.txt**" page.<br />
The home page of your fork of the **library-registry** repository will open.
1. You should see a banner on the page that says:

> **This branch is 1 commit ahead of arduino:main.**
Click the "**Contribute**" link near the right side of that banner.<br />
A menu will open.

1. Click the <kbd>Open pull request</kbd> button in the menu.<br />
The "**Open a pull request**" page will open.
1. In the **"Open a pull request"** window that opens, click the <kbd>Create pull request</kbd> button.

The library will be automatically checked for compliance as soon as the pull request is submitted. If no problems were
Expand Down

0 comments on commit 19ab8cf

Please sign in to comment.