@@ -0,0 +1,823 @@ | |||
<!doctype html><!-- This is a valid HTML5 document. --> | |||
<!-- Screen readers, SEO, extensions and so on. --> | |||
<html lang="fr"> | |||
<!-- Has to be within the first 1024 bytes, hence before the <title> | |||
See: https://www.w3.org/TR/2012/CR-html5-20121217/document-metadata.html#charset --> | |||
<meta charset="utf-8"> | |||
<!-- Why no `X-UA-Compatible` meta: https://stackoverflow.com/a/6771584 --> | |||
<!-- The viewport meta is quite crowded and we are responsible for that. | |||
See: https://codepen.io/tigt/post/meta-viewport-for-2015 --> | |||
<meta name="viewport" content="width=device-width,initial-scale=1"> | |||
<!-- Required to make a valid HTML5 document. --> | |||
<title>Git Branch Rename (archive) — David Larlet</title> | |||
<!-- That good ol' feed, subscribe :). --> | |||
<link rel="alternate" type="application/atom+xml" title="Feed" href="/david/log/"> | |||
<!-- Generated from https://realfavicongenerator.net/ such a mess. --> | |||
<link rel="apple-touch-icon" sizes="180x180" href="/static/david/icons2/apple-touch-icon.png"> | |||
<link rel="icon" type="image/png" sizes="32x32" href="/static/david/icons2/favicon-32x32.png"> | |||
<link rel="icon" type="image/png" sizes="16x16" href="/static/david/icons2/favicon-16x16.png"> | |||
<link rel="manifest" href="/static/david/icons2/site.webmanifest"> | |||
<link rel="mask-icon" href="/static/david/icons2/safari-pinned-tab.svg" color="#07486c"> | |||
<link rel="shortcut icon" href="/static/david/icons2/favicon.ico"> | |||
<meta name="msapplication-TileColor" content="#f0f0ea"> | |||
<meta name="msapplication-config" content="/static/david/icons2/browserconfig.xml"> | |||
<meta name="theme-color" content="#f0f0ea"> | |||
<!-- Documented, feel free to shoot an email. --> | |||
<link rel="stylesheet" href="/static/david/css/style_2020-06-19.css"> | |||
<!-- See https://www.zachleat.com/web/comprehensive-webfonts/ for the trade-off. --> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_regular.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_bold.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_italic.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_regular.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_bold.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_italic.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin> | |||
<script type="text/javascript"> | |||
function toggleTheme(themeName) { | |||
document.documentElement.classList.toggle( | |||
'forced-dark', | |||
themeName === 'dark' | |||
) | |||
document.documentElement.classList.toggle( | |||
'forced-light', | |||
themeName === 'light' | |||
) | |||
} | |||
const selectedTheme = localStorage.getItem('theme') | |||
if (selectedTheme !== 'undefined') { | |||
toggleTheme(selectedTheme) | |||
} | |||
</script> | |||
<meta name="robots" content="noindex, nofollow"> | |||
<meta content="origin-when-cross-origin" name="referrer"> | |||
<!-- Canonical URL for SEO purposes --> | |||
<link rel="canonical" href="https://github.com/chancancode/branch-rename/blob/main/README.md"> | |||
<body class="remarkdown h1-underline h2-underline h3-underline hr-center ul-star pre-tick"> | |||
<article> | |||
<h1>Git Branch Rename</h1> | |||
<nav> | |||
<p class="center"> | |||
<a href="/david/" title="Aller à l’accueil" tabindex="1">🏠</a> | |||
</p> | |||
</nav> | |||
<hr> | |||
<h2><a href="https://github.com/chancancode/branch-rename/blob/main/README.md">Source originale du contenu</a></h2> | |||
<p>So, you want to rename a branch on Git/GitHub. The most common case of this is | |||
to rename the default "master" branch to something else, such as "main". We are | |||
going to use this as our example, but you may have a different use case in | |||
mind. If that's the case, just replace "master" and "main" to the source and | |||
target branches you have in mind.</p> | |||
<h2><a id="user-content-table-of-contents" class="anchor" aria-hidden="true" href="#table-of-contents"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Table of Contents</h2> | |||
<h2><a id="user-content-new-project" class="anchor" aria-hidden="true" href="#new-project"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>New Project</h2> | |||
<p>If you are starting a brand new project, you can follow these steps:</p> | |||
<ol> | |||
<li> | |||
<p><a href="https://github.com/new">Create a new repository on GitHub</a> to host your | |||
project with the following settings:</p> | |||
<ul> | |||
<li><strong>Repository template</strong>: No template</li> | |||
<li><strong>Initialize this repository with a README</strong>: Leave unchecked</li> | |||
<li><strong>Add .gitignore</strong>: None</li> | |||
<li><strong>Add a license</strong>: None</li> | |||
</ul> | |||
<p>If you wish to use any of these features (i.e. with settings different than | |||
the above), that is not a problem. However, GitHub will create the default | |||
"master" branch for you. In that case, clone the repository locally and | |||
follow the steps in the <a href="#simple-migration"><strong>Simple Migration</strong></a> section | |||
instead.</p> | |||
</li> | |||
<li> | |||
<p>Initialize an empty Git repository:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ mkdir my-git-project | |||
$ <span class="pl-c1">cd</span> my-git-project | |||
$ git init <span class="pl-c1">.</span></pre></div> | |||
</li> | |||
<li> | |||
<p>Create the "main" branch:</p> | |||
</li> | |||
<li> | |||
<p>Work on your project and commit some changes. For example, add a README:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ <span class="pl-c1">echo</span> <span class="pl-s"><span class="pl-pds">"</span># My Git Project<span class="pl-pds">"</span></span> <span class="pl-k">>></span> README.md | |||
$ git add README.md | |||
$ git commit -m <span class="pl-s"><span class="pl-pds">"</span>Initial commit<span class="pl-pds">"</span></span></pre></div> | |||
</li> | |||
<li> | |||
<p>Push your commits to GitHub:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ git remote add origin https://github.com/your-username/my-git-project.git | |||
$ git push -u origin main</pre></div> | |||
</li> | |||
</ol> | |||
<p>That's all! Since "main" was the first branch you pushed to GitHub, it will be | |||
set correctly as the default branch. We also never committed any changes to the | |||
"master" branch locally, it effectively never existed so there is nothing left | |||
to clean up. Enjoy your new project!</p> | |||
<h2><a id="user-content-simple-migration" class="anchor" aria-hidden="true" href="#simple-migration"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Simple Migration</h2> | |||
<p>If you have a small personal project and you are comfortable with just doing | |||
the rename right away, here are the steps you can take.</p> | |||
<p>Note that if this is a <a href="https://pages.github.com">GitHub Pages</a> repository and | |||
the content is stored on the "master" branch, then you cannot perform the | |||
migration at this time since GitHub Pages does not seem to support alternative | |||
default branch names yet. If you want, you may follow the steps in the <a href="#local-migration"><strong>Local | |||
Migration</strong></a> or <a href="#gradual-migration"><strong>Gradual Migration</strong></a> | |||
section partially to get your project ready.</p> | |||
<ol> | |||
<li> | |||
<p>Pull the latest commits from the "master" branch into your local repository:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ <span class="pl-c1">cd</span> my-git-project | |||
$ git checkout master | |||
$ git pull origin master</pre></div> | |||
</li> | |||
<li> | |||
<p>Rename the local "master" branch to "main":</p> | |||
</li> | |||
<li> | |||
<p>Push the "main" branch to GitHub:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ git push -u origin main</pre></div> | |||
</li> | |||
<li> | |||
<p><a href="https://help.github.com/en/github/administering-a-repository/setting-the-default-branch">Change the default branch on GitHub</a> to "main".</p> | |||
</li> | |||
<li> | |||
<p>If there are existing pull requests open against the "master" branch that | |||
you would like to keep, <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/changing-the-base-branch-of-a-pull-request">update their base branch</a> to | |||
the "main" branch. Otherwise, they will be closed automatically when we | |||
delete the remote "master" branch on GitHub.</p> | |||
</li> | |||
<li> | |||
<p>Delete your local "master" branch:</p> | |||
</li> | |||
<li> | |||
<p>Delete the remote "master" branch:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ git push origin :master</pre></div> | |||
</li> | |||
</ol> | |||
<p>At this point, the migration is complete. However, as you work on the project, | |||
you may discover additional settings that you need to tweak to account for the | |||
rename. For example, you may have update the branch names in your CI config.</p> | |||
<h2><a id="user-content-gradual-migration" class="anchor" aria-hidden="true" href="#gradual-migration"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Gradual Migration</h2> | |||
<p>If you have a work or open-source repository with multiple contributors and | |||
forks, you may prefer to perform the migration gradually.</p> | |||
<p>These steps are for you if you find yourself in a similar scenario, where it is | |||
important to give everyone ample of time to prepare for the migration, changing | |||
local configs, adapting workflows, scripts and other automation to ensure a | |||
seamless migration.</p> | |||
<p>This gradual migration plan is intended to be spread out over a long period of | |||
time – weeks, or months. It uses all available tools on GitHub to provide as | |||
much advance notice as possible.</p> | |||
<p>For most organizations, this plan may be overly cautious and some of the steps | |||
may not be necessary. On the other hand, for a popular open-source project, it | |||
may not be feasible to get to the end and fully deprecate and remove the legacy | |||
"master" branch at all, due to compatibility requirements. Treat this plan as a | |||
template and adapt it for your own needs.</p> | |||
<p>Unlike the other sections, the steps here are a bit less exact and is intended | |||
for someone with a some prior experience with Git and GitHub. In practice, you | |||
will probably run into situations that causes deviations from the plan which | |||
would require some manual repair and adjustments. For example, pushes during a | |||
partial GitHub outage may cause the two branches to diverge and requires you | |||
to determine how to best reconcile the differences.</p> | |||
<h3><a id="user-content-phase-1-mirror-master-and-main" class="anchor" aria-hidden="true" href="#phase-1-mirror-master-and-main"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Phase 1: Mirror "master" and "main"</h3> | |||
<p>The goal of this phase is to make it <em>possible</em> to use the "main" branch name | |||
as an alternative. This allows some early adopters to start testing the new | |||
setup.</p> | |||
<ol> | |||
<li> | |||
<p>As always, make sure your local "master" branch is up-to-date.</p> | |||
</li> | |||
<li> | |||
<p>Create the new "main" branch:</p> | |||
</li> | |||
<li> | |||
<p>Add a <a href="https://github.com/features/actions">GitHub Actions</a> workflow file at | |||
<strong>.github/workflows/mirror-master-and-main.yml</strong> with the following:</p> | |||
<div class="highlight highlight-source-yaml"><pre><span class="pl-ent">name</span>: <span class="pl-s">Mirror "master" and "main" branches</span> | |||
<span class="pl-ent">on</span>: | |||
<span class="pl-ent">push</span>: | |||
<span class="pl-ent">branches</span>: | |||
- <span class="pl-s">master</span> | |||
- <span class="pl-s">main</span> | |||
<span class="pl-ent">jobs</span>: | |||
<span class="pl-ent">mirror</span>: | |||
<span class="pl-ent">runs-on</span>: <span class="pl-s">ubuntu-latest</span> | |||
<span class="pl-ent">steps</span>: | |||
- <span class="pl-ent">name</span>: <span class="pl-s">Mirror to "master"</span> | |||
<span class="pl-ent">uses</span>: <span class="pl-s">zofrex/mirror-branch@v1</span> | |||
<span class="pl-ent">with</span>: | |||
<span class="pl-ent">target-branch</span>: <span class="pl-s">master</span> | |||
<span class="pl-ent">force</span>: <span class="pl-c1">false</span> | |||
- <span class="pl-ent">name</span>: <span class="pl-s">Mirror to "main"</span> | |||
<span class="pl-ent">uses</span>: <span class="pl-s">zofrex/mirror-branch@v1</span> | |||
<span class="pl-ent">with</span>: | |||
<span class="pl-ent">target-branch</span>: <span class="pl-s">main</span> | |||
<span class="pl-ent">force</span>: <span class="pl-c1">false</span></pre></div> | |||
</li> | |||
<li> | |||
<p>Commit and your changes to the local "main" branch.</p> | |||
</li> | |||
<li> | |||
<p>Push your changes to the remote "main" branch:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ git push -u origin main</pre></div> | |||
</li> | |||
</ol> | |||
<p>If things are working correctly, you should see the same commit pushed to the | |||
"master" branch shortly. You can monitor the progress and unexpected errors in | |||
the "Actions" tab in your repository.</p> | |||
<h4><a id="user-content-about-github-actions" class="anchor" aria-hidden="true" href="#about-github-actions"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>About GitHub Actions</h4> | |||
<p>You do not have to be already using GitHub Actions for this to work. You do not | |||
need to activate or enable the feature for your repository, simply pushing the | |||
workflow file to the is sufficient. All open-source repositories have unlimited | |||
GitHub Actions minutes, and all personal and team accounts comes with 2000-3000 | |||
free GitHub Actions minutes for private repositories.</p> | |||
<p>If you already regularly uses up your free minutes, this may slightly increase | |||
your GitHub bills, but in practice, the workflow we added runs very quickly so | |||
the impact is very minimal. For reference, GitHub Actions are billed at $0.008 | |||
USD per minute for private repositories, after the free quota is exhausted.</p> | |||
<p>This workflow will be triggered when commits are pushed to either the "master" | |||
or "main" branch. It uses the <a href="https://github.com/marketplace/actions/mirror-branch">Mirror Branch action</a> to | |||
update the branches using GitHub's API.</p> | |||
<h4><a id="user-content-interaction-with-branch-protection" class="anchor" aria-hidden="true" href="#interaction-with-branch-protection"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Interaction with Branch Protection</h4> | |||
<p>Unfortunately, if you have enabled <a href="https://help.github.com/en/github/administering-a-repository/configuring-protected-branches">branch protection</a> on | |||
the "master" branch, the push from the mirroring action may be rejected. For | |||
example, if you had enabled "Require pull request reviews before merging", then | |||
this would not work as the changes are expected to be submitted via a pull | |||
request with reviews.</p> | |||
<p>A possible workaround is to disable the "Include administrators" checkbox in | |||
the branch protection settings for the "master" branch and configure the script | |||
to push the commits as an administrator:</p> | |||
<ol> | |||
<li> | |||
<p>Login as an administrator on GitHub. You may also want to consider creating | |||
a new account specifically for this purpose.</p> | |||
</li> | |||
<li> | |||
<p>Generate a <a href="https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line">personal access token</a> with the "repo" | |||
scope (and the "public_repo" scope, if needed).</p> | |||
</li> | |||
<li> | |||
<p><a href="https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets-for-a-repository">Add it as a secret</a> to the repository.</p> | |||
</li> | |||
<li> | |||
<p>Change the "Checkout" step in the mirror workflow to use the new deploy key:</p> | |||
<div class="highlight highlight-source-yaml"><pre>- <span class="pl-ent">name</span>: <span class="pl-s">Checkout</span> | |||
<span class="pl-ent">uses</span>: <span class="pl-s">actions/checkout@v2</span> | |||
<span class="pl-ent">with</span>: | |||
<span class="pl-ent">token</span>: <span class="pl-s">${{ secrets.DEPLOY_TOKEN }}</span></pre></div> | |||
<p>Here, <code>DEPLOY_TOKEN</code> is the name you picked from step 3.</p> | |||
</li> | |||
</ol> | |||
<p>Alternatively, an SSH key for the administrator can be used instead of a | |||
personal access token, via the <code>ssh-key</code> argument. See the documentation for | |||
the <a href="https://github.com/actions/checkout">checkout action</a> for more details.</p> | |||
<h4><a id="user-content-interaction-with-other-github-action-workflows" class="anchor" aria-hidden="true" href="#interaction-with-other-github-action-workflows"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Interaction with Other GitHub Action Workflows</h4> | |||
<p>By default, when pushing commits from within the GitHub Actions job, it does | |||
not trigger additional GitHub Actions workflow to run. For example, when a | |||
contributor pushes to the "main" branch, it will trigger any GitHub Actions | |||
that normally runs on the "main" branch's push events, including the one we | |||
added here. However, when our mirror workflow pushes the same commit to the | |||
"master" branch, it will not trigger any workflow that normally runs on the | |||
"master" branch's push events.</p> | |||
<p>For this reason, you may want to update existing workflows that runs on the | |||
"master" branch to also run on the "main" branch, as we did in our mirror | |||
workflow file (the <code>on.push.branches</code> config key). This is the recommended | |||
approach as it ensures only a single build per push.</p> | |||
<p>Alternatively, if it is important to you that workflows are triggered by pushes | |||
from the mirror workflow, you can accomplish this by supplying an alternative | |||
SSH key to the <a href="https://github.com/actions/checkout">checkout action</a>:</p> | |||
<ol> | |||
<li> | |||
<p><a href="https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent">Generate a new SSH key</a> locally. Don't worry about adding | |||
it to the ssh-agent.</p> | |||
</li> | |||
<li> | |||
<p>Find the generated <em>public key</em> and <a href="https://developer.github.com/v3/guides/managing-deploy-keys/#deploy-keys">add it as a deploy key</a> | |||
to the repository. Be sure to select "Allow write access".</p> | |||
</li> | |||
<li> | |||
<p>Find the generated <em>private key</em> and <a href="https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets-for-a-repository">add it as a secret</a> to the | |||
repository.</p> | |||
</li> | |||
<li> | |||
<p>Change the "Checkout" step in the mirror workflow to use the new deploy key:</p> | |||
<div class="highlight highlight-source-yaml"><pre>- <span class="pl-ent">name</span>: <span class="pl-s">Checkout</span> | |||
<span class="pl-ent">uses</span>: <span class="pl-s">actions/checkout@v2</span> | |||
<span class="pl-ent">with</span>: | |||
<span class="pl-ent">ssh-key</span>: <span class="pl-s">${{ secrets.DEPLOY_KEY }}</span></pre></div> | |||
<p>Here, <code>DEPLOY_KEY</code> is the name you picked from step 3.</p> | |||
</li> | |||
</ol> | |||
<p>With this, the mirror workflow will authenticate with GitHub using the deploy | |||
key instead of the default token when pushing commits, triggering any workflows | |||
as if a regular user had pushed those commits. This does not change the author | |||
or committer on the commits.</p> | |||
<h4><a id="user-content-real-world-example" class="anchor" aria-hidden="true" href="#real-world-example"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Real World Example</h4> | |||
<p>See <a href="https://github.com/chancancode/ember-concurrency-async/commit/afbacf7088e473dd056138109e00d8749b95b2d0">this commit</a> and <a href="https://github.com/chancancode/ember-concurrency-async/runs/788797792?check_suite_focus=true">the resulting workflow run</a> | |||
for an example of this working in action. Note that the code in the commit may | |||
be outdated by the time you read this – refer to the above for the latest | |||
instructions.</p> | |||
<h4><a id="user-content-next-steps" class="anchor" aria-hidden="true" href="#next-steps"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Next Steps</h4> | |||
<p>After verifying that everything is working as intended, you can start inviting | |||
the early adopters to start pushing to the "main" branch. The easiest way to do | |||
this is to rename the local "master" branch:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ <span class="pl-c1">cd</span> my-git-project | |||
$ git checkout master | |||
$ git branch -m main | |||
$ git branch -u origin/main</pre></div> | |||
<p>This would also be a good time to start changing any automation or external | |||
services to the "main" branch to ensure that everything is working as expected.</p> | |||
<h3><a id="user-content-phase-2-change-the-default-branch-to-main-deprecate-master" class="anchor" aria-hidden="true" href="#phase-2-change-the-default-branch-to-main-deprecate-master"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Phase 2: Change the default branch to "main", deprecate "master"</h3> | |||
<p>After verifying the viability of the rename during the previous phase, the goal | |||
of this phase is to set "main" as the default branch and start issuing | |||
deprecation warnings when the legacy "master" branch is used.</p> | |||
<ol> | |||
<li> | |||
<p><a href="https://help.github.com/en/github/administering-a-repository/setting-the-default-branch">Change the default branch on GitHub</a> to "main".</p> | |||
</li> | |||
<li> | |||
<p>Add a <a href="https://github.com/features/actions">GitHub Actions</a> workflow file at | |||
<strong>.github/workflows/deprecate-master-branch.yml</strong> with the following:</p> | |||
<div class="highlight highlight-source-yaml"><pre><span class="pl-ent">name</span>: <span class="pl-s">Deprecate "master" branch</span> | |||
<span class="pl-ent">on</span>: | |||
<span class="pl-ent">push</span>: | |||
<span class="pl-ent">branches</span>: | |||
- <span class="pl-s">master</span> | |||
<span class="pl-ent">pull_request</span>: | |||
<span class="pl-ent">branches</span>: | |||
- <span class="pl-s">master</span> | |||
<span class="pl-ent">jobs</span>: | |||
<span class="pl-ent">on-push</span>: | |||
<span class="pl-ent">runs-on</span>: <span class="pl-s">ubuntu-latest</span> | |||
<span class="pl-ent">if</span>: <span class="pl-s">${{ github.event_name == 'push' }}</span> | |||
<span class="pl-ent">steps</span>: | |||
- <span class="pl-ent">name</span>: <span class="pl-s">Deprecation</span> | |||
<span class="pl-ent">uses</span>: <span class="pl-s">peter-evans/commit-comment@v1</span> | |||
<span class="pl-ent">with</span>: | |||
<span class="pl-ent">body</span>: <span class="pl-s">|</span> | |||
<span class="pl-s"> Hello @${{ github.event.sender.login }}!</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> I see that you have pushed some commits to the "master" branch. We are in the process of renaming the "master" branch to "main" in this repository.</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> :warning: **The "master" branch is deprecated and will be removed from this repository in the future.**</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> Please migrate your local repository by renaming the "master" branch to "main":</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> ```bash</span> | |||
<span class="pl-s"> $ cd my-git-project</span> | |||
<span class="pl-s"> $ git checkout master</span> | |||
<span class="pl-s"> $ git branch -m main</span> | |||
<span class="pl-s"> $ git branch -u origin/main</span> | |||
<span class="pl-s"> ```</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> Before merging pull requests, ensure their base branch is set to "main" instead of "master". For more information on how to do this, refer to [this GitHub support article][1].</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> [1]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/changing-the-base-branch-of-a-pull-request</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"/> <span class="pl-ent">on-pull-request</span>: | |||
<span class="pl-ent">runs-on</span>: <span class="pl-s">ubuntu-latest</span> | |||
<span class="pl-ent">if</span>: <span class="pl-s">${{ github.event_name == 'pull_request' }}</span> | |||
<span class="pl-ent">env</span>: | |||
<span class="pl-ent">DEPRECATION_MESSAGE</span>: <span class="pl-s">|</span> | |||
<span class="pl-s"> Hello @${{ github.event.sender.login }}!</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> I see that you have opened a pull request against the "master" branch. We are in the process of renaming the "master" branch to "main" in this repository.</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> :warning: **The "master" branch is deprecated and will be removed from this repository in the future.**</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> Please migrate your local repository by renaming the "master" branch to "main":</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> ```bash</span> | |||
<span class="pl-s"> $ cd my-git-project</span> | |||
<span class="pl-s"> $ git checkout master</span> | |||
<span class="pl-s"> $ git branch -m main</span> | |||
<span class="pl-s"> $ git branch -u origin/main</span> | |||
<span class="pl-s"> ```</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> Please also set the base branch for this pull request to "main" instead of "master". For more information on how to do this, refer to [this GitHub support article][1].</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> [1]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/changing-the-base-branch-of-a-pull-request</span> | |||
<span class="pl-s"/> <span class="pl-ent">steps</span>: | |||
- <span class="pl-ent">name</span>: <span class="pl-s">Deprecation</span> | |||
<span class="pl-ent">if</span>: <span class="pl-s">${{ github.event.pull_request.head.repo.fork == false }}</span> | |||
<span class="pl-ent">uses</span>: <span class="pl-s">peter-evans/create-or-update-comment@v1</span> | |||
<span class="pl-ent">with</span>: | |||
<span class="pl-ent">issue-number</span>: <span class="pl-s">${{ github.event.number }}</span> | |||
<span class="pl-ent">body</span>: <span class="pl-s">${{ env.DEPRECATION_MESSAGE }}</span> | |||
- <span class="pl-ent">name</span>: <span class="pl-s">Deprecation</span> | |||
<span class="pl-ent">if</span>: <span class="pl-s">${{ github.event.pull_request.head.repo.fork == true }}</span> | |||
<span class="pl-ent">run</span>: <span class="pl-s">|</span> | |||
<span class="pl-s"> echo "$DEPRECATION_MESSAGE"</span> | |||
<span class="pl-s"> echo '::error::Please set the base branch for this pull request to "main" instead of "master".'</span> | |||
<span class="pl-s"> exit 1</span></pre></div> | |||
</li> | |||
<li> | |||
<p>Commit and push your changes to the "main" branch.</p> | |||
</li> | |||
</ol> | |||
<p>We added a workflow file that triggers whenever a contributor pushes to or | |||
opens a pull request against the "master" branch.</p> | |||
<p>The workflow adds a comment to the commit or pull request, notifying the | |||
contributor that the "master" branch has been deprecated, along with the steps | |||
they need to take to migrate their local repository and changes they need to | |||
make it to the pull request.</p> | |||
<p>It is recommended that you customize the messages with additional information | |||
relevant for your organization. For example, you may want to include a link to | |||
a tracking issue for additional context, or ways for the contributor to ask for | |||
additional assistance if needed.</p> | |||
<h4><a id="user-content-limitations-of-github-actions-in-forks" class="anchor" aria-hidden="true" href="#limitations-of-github-actions-in-forks"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Limitations of GitHub Actions in Forks</h4> | |||
<p>Unfortunately, due to limitations of GitHub Actions, it is not possible to add | |||
a pull request comment from the workflow when the pull request originated from | |||
a fork, which is very common in open-source repositories. As a workaround, the | |||
workflow prints the deprecation message to the logs and fails the build.</p> | |||
<h4><a id="user-content-real-world-example-1" class="anchor" aria-hidden="true" href="#real-world-example-1"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Real World Example</h4> | |||
<p>See <a href="https://github.com/chancancode/ember-concurrency-async/commit/7f3509b4363f3fcdb3275ec136c4b5766f39c192">this commit</a> and <a href="https://github.com/chancancode/ember-concurrency-async/pull/5">this pull request</a> for an | |||
example of this working in action. Note that the code in the commit may be | |||
outdated by the time you read this – refer to the above for the latest | |||
instructions.</p> | |||
<h4><a id="user-content-next-steps-1" class="anchor" aria-hidden="true" href="#next-steps-1"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Next Steps</h4> | |||
<p>This would be a good time to start updating any internal and external links to | |||
the "master" branch. A common example would be automatically generated links to | |||
source code from the API documentation.</p> | |||
<h3><a id="user-content-phase-3-complete-the-migration" class="anchor" aria-hidden="true" href="#phase-3-complete-the-migration"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Phase 3: Complete the migration</h3> | |||
<p>After a successful phase 2 rollout, it is time to plan for completing the | |||
migration. However, what completion means is going to be different depending on | |||
your situation.</p> | |||
<p>For private work repositories, the legacy "master" branch can likely be removed | |||
from the repository after giving team members a few weeks to migrate. Don't | |||
forget to remove the workflow files as well.</p> | |||
<p>For open-source repositories with lots of contributors, you may want to move a | |||
lot slower. Monitor the Actions tab of the repository to see how often the | |||
deprecation workflow is triggered. When the activity diminishes, it may be good | |||
indication that the legacy "master" branch is no longer needed.</p> | |||
<h4><a id="user-content-soft-removal" class="anchor" aria-hidden="true" href="#soft-removal"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Soft Removal</h4> | |||
<p>As an alternative to removing the branch right away, you may want to consider | |||
pushing a final commit to the branch, removing all files but leave behind a | |||
README file explaining that branch has been moved, along with the steps they | |||
need to take in order to migrate their local repository.</p> | |||
<h4><a id="user-content-url-considerations" class="anchor" aria-hidden="true" href="#url-considerations"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>URL Considerations</h4> | |||
<p>It is also important to consider URL breakages, as links that points to the | |||
files on the "master" branch will stop working once the branch is removed, | |||
including with the soft-removal method described above.</p> | |||
<p>The impact of this has to be evaluated contextually, but it is important to | |||
note that the scope of the breakage is fairly limited, as this only directly | |||
impacts URLs that links to the "master" branch directly. Links pointing to the | |||
active development branch of repository is quite fragile (especially with line | |||
numbers) and often breaks for other reasons.</p> | |||
<p>For example, a refactor that moves around files or switching from JavaScript to | |||
TypeScript would invalidate these URLs. This sort of activity is fairly common | |||
on an active code repository and is usually performed without taking the URL | |||
consideration in mind. For this reason, it is considered a best practice to use | |||
SHA-based <a href="https://help.github.com/en/github/managing-files-in-a-repository/getting-permanent-links-to-files">permanent links</a> in most situations. These links | |||
are unaffected by the branch rename.</p> | |||
<h4><a id="user-content-packages-considerations" class="anchor" aria-hidden="true" href="#packages-considerations"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Packages Considerations</h4> | |||
<p>For repositories containing <em>installable packages</em>, there are some additional | |||
considerations. Many package managers allow for installing packages from a Git | |||
repository. For example, in npm and yarn, dependencies can be a string like | |||
"username/repo" or "username/repo#branch" in lieu of version range. Likewise, | |||
GitHub Actions are installed using repository and branch references, and it is | |||
a relatively common practice to point an action at the "master" branch.</p> | |||
<p>In these cases, the decision on whether to remove the legacy "master" branch | |||
has to be made carefully. Here are some examples of things to investigate | |||
and consider:</p> | |||
<ul> | |||
<li> | |||
<p>When the branch is omitted from the specifier (e.g. "username/repo"), does | |||
the package manager in your ecosystem hard-code the default to "master" on | |||
the client, or does it respect the remote HEAD ref?</p> | |||
</li> | |||
<li> | |||
<p>Does the package manager use a lockfile, and if so, does it serialize the | |||
branch name (as opposed to the resolved SHA) into the lockfile?</p> | |||
</li> | |||
<li> | |||
<p>Does the package manager maintain a cache of cloned repositories, and if so | |||
do they recover gracefully to a remote branch disappearing?</p> | |||
</li> | |||
</ul> | |||
<p>The answer to these questions affects the potential impact to your end-users | |||
if the legacy "master" branch is removed from the repository. For some, the | |||
end-state of the migration may be to keep the "master" branch permanently as a | |||
read-only mirror, or it may be sufficient to freeze the branch's content and | |||
stop providing updates there. For others, the potential breakage maybe small | |||
enough that it is can be easily justified.</p> | |||
<p>While the workflows added in phase 2 are effective for deprecating <em>writes</em> to | |||
the legacy "master" branch. Unfortunately, Git and GitHub do not offer the | |||
ability to do the same for <em>reads</em> to the branch.</p> | |||
<p>However, you may be able to use features from the package manager to accomplish | |||
a similar result. For example, instead of mirroring the "main" branch to the | |||
"master" branch exactly, you could add a post-install hook to the version on | |||
"master" to issue the deprecation message for any potential consumers.</p> | |||
<h4><a id="user-content-a-concrete-example" class="anchor" aria-hidden="true" href="#a-concrete-example"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>A Concrete Example</h4> | |||
<p>Using the Node.js ecosystem as an example, we can put these considerations into | |||
context, based on preliminary testing with npm and yarn classic (v1). If you | |||
found different results in your own testing, or with other package managers | |||
(pnpm, yarn v2, etc), please file an issue here.</p> | |||
<ul> | |||
<li> | |||
<p>The popular package managers in the ecosystem support installing packages | |||
from git, by specifying "username/repo" or "username/repo#branch" in the | |||
dependencies section of package.json.</p> | |||
</li> | |||
<li> | |||
<p>When a branch name is not specified, the popular package managers defaults to | |||
the remote HEAD ref, which is set by the default branch on GitHub, instead of | |||
hardcoding to the "master" branch in the client.</p> | |||
</li> | |||
<li> | |||
<p>The popular package managers uses a lockfile by default. They serialize the | |||
resolved SHA into the lockfiles, as long as the commits referred to by these | |||
SHAs remain reachable on the remote repository, they will install just fine | |||
when using a lockfile. In the case of a branch rename, this is not an issue, | |||
as the history and commits will remain intact.</p> | |||
</li> | |||
<li> | |||
<p>When installing without a lockfile, the popular package managers will fetch | |||
the latest commit from the repository. Renaming the remote branch did not | |||
appear to cause any issues, either because the repositories are not cached, | |||
or the clients are able to recover gracefully from a "missing" remote branch.</p> | |||
</li> | |||
<li> | |||
<p>Post-install hooks are supported. However, yarn classic <a href="https://github.com/yarnpkg/yarn/issues/5476">hides the output | |||
produced by these scripts</a> if | |||
they are successful (exit cleanly with exit code 0). However, when they fail, | |||
they output <em>is</em> shown to the user.</p> | |||
</li> | |||
<li> | |||
<p>Generally speaking, the ecosystem has strong norms and expectations around | |||
adhering to <a href="https://semver.org" rel="nofollow">semantic versioning</a>. Usually, breaking changes are only | |||
expected on major version bumps.</p> | |||
</li> | |||
<li> | |||
<p>By using a Git dependency instead of specifying a semver range, they are | |||
explicitly opting out of the normal semver guarantee, and breakages are to be | |||
expected. No one could reasonably expect that pointing a dependency to the | |||
active development branch without using a lockfile will result in a stable | |||
system.</p> | |||
</li> | |||
</ul> | |||
<p>Given these findings, here is a concrete proposal for a maximally graceful | |||
completion plan:</p> | |||
<ol> | |||
<li> | |||
<p>Stop providing updates to the "master" branch by removing the mirroring | |||
workflow added in phase 1.</p> | |||
</li> | |||
<li> | |||
<p>Push a commit the "master" branch, updating the README as well as adding a | |||
deprecation message to the runtime code (the <code>main</code> entry point):</p> | |||
<div class="highlight highlight-source-js"><pre><span class="pl-c">// index.js</span> | |||
<span class="pl-k">let</span> <span class="pl-s1">command</span> <span class="pl-c1">=</span> <span class="pl-s">'npm update my-git-project'</span><span class="pl-kos">;</span> | |||
<span class="pl-k">if</span> <span class="pl-kos">(</span><span class="pl-s1">process</span><span class="pl-kos">.</span><span class="pl-c1">env</span><span class="pl-kos">.</span><span class="pl-c1">npm_execpath</span> <span class="pl-c1">&&</span> <span class="pl-s1">process</span><span class="pl-kos">.</span><span class="pl-c1">env</span><span class="pl-kos">.</span><span class="pl-c1">npm_execpath</span><span class="pl-kos">.</span><span class="pl-en">indexOf</span><span class="pl-kos">(</span><span class="pl-s">'yarn'</span><span class="pl-kos">)</span> !== <span class="pl-c1">-</span><span class="pl-c1">1</span><span class="pl-kos">)</span> <span class="pl-kos">{</span> | |||
<span class="pl-s1">command</span> <span class="pl-c1">=</span> <span class="pl-s">'yarn upgrade my-git-project'</span><span class="pl-kos">;</span> | |||
<span class="pl-kos">}</span> | |||
<span class="pl-smi">console</span><span class="pl-kos">.</span><span class="pl-en">warn</span><span class="pl-kos">(</span> | |||
<span class="pl-s">`You are running a deprecated copy of the "my-git-project" installed `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`from the "master" branch of our repository. The "master" branch is `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`deprecated and no longer receives any updates. The branch will soon `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`be removed from our repository, at which point the package will fail `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`to install.\n\n`</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`To fix this issue, please modify your package.json and change the `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`"my-git-project" dependency from "my-repo/my-git-project#master" to `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`"my-repo/my-git-project" or a valid semver range. After making the `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`change, run "<span class="pl-s1"><span class="pl-kos">${</span><span class="pl-s1">command</span><span class="pl-kos">}</span></span>" to update the package.`</span> | |||
<span class="pl-kos">)</span><span class="pl-kos">;</span> | |||
<span class="pl-c">// ...rest of index.js</span></pre></div> | |||
</li> | |||
<li> | |||
<p>When releasing the next major version of the package, push another commit to | |||
the "master" branch, remove all files from the branch, leaving behind only a | |||
minimal README file, package.json and index.js:</p> | |||
<div class="highlight highlight-source-js"><pre><span class="pl-c">// package.json</span> | |||
<span class="pl-kos">{</span> | |||
<span class="pl-s">"name"</span>: <span class="pl-s">"my-git-project"</span><span class="pl-kos">,</span> | |||
<span class="pl-s">"scripts"</span>: <span class="pl-kos">{</span> | |||
<span class="pl-s">"postinstall"</span>: <span class="pl-s">"node index.js"</span> | |||
<span class="pl-kos">}</span> | |||
<span class="pl-kos">}</span></pre></div> | |||
<div class="highlight highlight-source-js"><pre><span class="pl-c">// index.js</span> | |||
<span class="pl-k">let</span> <span class="pl-s1">command</span> <span class="pl-c1">=</span> <span class="pl-s">'npm update my-git-project'</span><span class="pl-kos">;</span> | |||
<span class="pl-k">if</span> <span class="pl-kos">(</span><span class="pl-s1">process</span><span class="pl-kos">.</span><span class="pl-c1">env</span><span class="pl-kos">.</span><span class="pl-c1">npm_execpath</span> <span class="pl-c1">&&</span> <span class="pl-s1">process</span><span class="pl-kos">.</span><span class="pl-c1">env</span><span class="pl-kos">.</span><span class="pl-c1">npm_execpath</span><span class="pl-kos">.</span><span class="pl-en">indexOf</span><span class="pl-kos">(</span><span class="pl-s">'yarn'</span><span class="pl-kos">)</span> !== <span class="pl-c1">-</span><span class="pl-c1">1</span><span class="pl-kos">)</span> <span class="pl-kos">{</span> | |||
<span class="pl-s1">command</span> <span class="pl-c1">=</span> <span class="pl-s">'yarn upgrade my-git-project'</span><span class="pl-kos">;</span> | |||
<span class="pl-kos">}</span> | |||
<span class="pl-smi">console</span><span class="pl-kos">.</span><span class="pl-en">error</span><span class="pl-kos">(</span> | |||
<span class="pl-s">`You have installed "my-git-project" from the "master" branch of our `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`repository. The "master" branch has been official retired.\n\n`</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`To fix this issue, please modify your package.json and change the `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`"my-git-project" dependency from "my-repo/my-git-project#master" to `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`"my-repo/my-git-project" or a valid semver range. After making the `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`change, run "<span class="pl-s1"><span class="pl-kos">${</span><span class="pl-s1">command</span><span class="pl-kos">}</span></span>" to update the package.`</span> | |||
<span class="pl-kos">)</span><span class="pl-kos">;</span> | |||
<span class="pl-s1">process</span><span class="pl-kos">.</span><span class="pl-en">exit</span><span class="pl-kos">(</span><span class="pl-c1">1</span><span class="pl-kos">)</span><span class="pl-kos">;</span></pre></div> | |||
</li> | |||
<li> | |||
<p>After some time, the master branch can be removed from the repository. This | |||
does not constitute a breaking change, as the package already ceased to | |||
function as of the previous commit. It was just a courteous message to ease | |||
confusion and provide actionable instructions for fixing the issue.</p> | |||
</li> | |||
</ol> | |||
<p>For most projects and organizations, this amount of notice is probably not | |||
necessary or warranted, but it showcases the available tools and techniques, | |||
and demonstrates that there can be a good migration path even under very strict | |||
compatibility requirements. As always, use these steps as a template and tailor | |||
them to your own needs.</p> | |||
<h2><a id="user-content-local-migration" class="anchor" aria-hidden="true" href="#local-migration"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Local Migration</h2> | |||
<p>Finally, if you are working on a repository you don't control, and you would | |||
like to refer to your local branch with a different name without making any | |||
changes to the upstream project, you can rename your local "master" branch to | |||
"main" with these steps:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ <span class="pl-c1">cd</span> my-git-project | |||
$ git checkout master | |||
$ git branch -m main | |||
$ git branch -u origin/master</pre></div> | |||
<p>This renames the local branch to "main" but sets the remote tracking branch to | |||
"master".</p> | |||
<h2><a id="user-content-license" class="anchor" aria-hidden="true" href="#license"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>License</h2> | |||
<p>This content in this repository, including this documentation and code examples | |||
are licensed under the <a href="https://creativecommons.org/share-your-work/public-domain/cc0/" rel="nofollow">CC0 "No Rights Reserved"</a> public domain | |||
license. Feel free to reproduce and adapt this work into your own proposals, | |||
documentation, etc.</p> | |||
<p>Attribution is not necessary. However, this guide receives constant updates to | |||
reflect current best-practice and solutions based implementation feedback, so | |||
a reference to this repository may be helpful.</p> | |||
</article> | |||
<hr> | |||
<footer> | |||
<p> | |||
<a href="/david/" title="Aller à l’accueil">🏠</a> • | |||
<a href="/david/log/" title="Accès au flux RSS">🤖</a> • | |||
<a href="http://larlet.com" title="Go to my English profile" data-instant>🇨🇦</a> • | |||
<a href="mailto:david%40larlet.fr" title="Envoyer un courriel">📮</a> • | |||
<abbr title="Hébergeur : Alwaysdata, 62 rue Tiquetonne 75002 Paris, +33184162340">🧚</abbr> | |||
</p> | |||
<template id="theme-selector"> | |||
<form> | |||
<fieldset> | |||
<legend>Thème</legend> | |||
<label> | |||
<input type="radio" value="auto" name="chosen-color-scheme" checked> Auto | |||
</label> | |||
<label> | |||
<input type="radio" value="dark" name="chosen-color-scheme"> Foncé | |||
</label> | |||
<label> | |||
<input type="radio" value="light" name="chosen-color-scheme"> Clair | |||
</label> | |||
</fieldset> | |||
</form> | |||
</template> | |||
</footer> | |||
<script type="text/javascript"> | |||
function loadThemeForm(templateName) { | |||
const themeSelectorTemplate = document.querySelector(templateName) | |||
const form = themeSelectorTemplate.content.firstElementChild | |||
themeSelectorTemplate.replaceWith(form) | |||
form.addEventListener('change', (e) => { | |||
const chosenColorScheme = e.target.value | |||
localStorage.setItem('theme', chosenColorScheme) | |||
toggleTheme(chosenColorScheme) | |||
}) | |||
const selectedTheme = localStorage.getItem('theme') | |||
if (selectedTheme && selectedTheme !== 'undefined') { | |||
form.querySelector(`[value="${selectedTheme}"]`).checked = true | |||
} | |||
} | |||
const prefersColorSchemeDark = '(prefers-color-scheme: dark)' | |||
window.addEventListener('load', () => { | |||
let hasDarkRules = false | |||
for (const styleSheet of Array.from(document.styleSheets)) { | |||
let mediaRules = [] | |||
for (const cssRule of styleSheet.cssRules) { | |||
if (cssRule.type !== CSSRule.MEDIA_RULE) { | |||
continue | |||
} | |||
// WARNING: Safari does not have/supports `conditionText`. | |||
if (cssRule.conditionText) { | |||
if (cssRule.conditionText !== prefersColorSchemeDark) { | |||
continue | |||
} | |||
} else { | |||
if (cssRule.cssText.startsWith(prefersColorSchemeDark)) { | |||
continue | |||
} | |||
} | |||
mediaRules = mediaRules.concat(Array.from(cssRule.cssRules)) | |||
} | |||
// WARNING: do not try to insert a Rule to a styleSheet you are | |||
// currently iterating on, otherwise the browser will be stuck | |||
// in a infinite loop… | |||
for (const mediaRule of mediaRules) { | |||
styleSheet.insertRule(mediaRule.cssText) | |||
hasDarkRules = true | |||
} | |||
} | |||
if (hasDarkRules) { | |||
loadThemeForm('#theme-selector') | |||
} | |||
}) | |||
</script> | |||
</body> | |||
</html> |
@@ -0,0 +1,594 @@ | |||
title: Git Branch Rename | |||
url: https://github.com/chancancode/branch-rename/blob/main/README.md | |||
hash_url: 240b647e699da81b505d43af39257996 | |||
<p>So, you want to rename a branch on Git/GitHub. The most common case of this is | |||
to rename the default "master" branch to something else, such as "main". We are | |||
going to use this as our example, but you may have a different use case in | |||
mind. If that's the case, just replace "master" and "main" to the source and | |||
target branches you have in mind.</p> | |||
<h2><a id="user-content-table-of-contents" class="anchor" aria-hidden="true" href="#table-of-contents"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Table of Contents</h2> | |||
<h2><a id="user-content-new-project" class="anchor" aria-hidden="true" href="#new-project"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>New Project</h2> | |||
<p>If you are starting a brand new project, you can follow these steps:</p> | |||
<ol> | |||
<li> | |||
<p><a href="https://github.com/new">Create a new repository on GitHub</a> to host your | |||
project with the following settings:</p> | |||
<ul> | |||
<li><strong>Repository template</strong>: No template</li> | |||
<li><strong>Initialize this repository with a README</strong>: Leave unchecked</li> | |||
<li><strong>Add .gitignore</strong>: None</li> | |||
<li><strong>Add a license</strong>: None</li> | |||
</ul> | |||
<p>If you wish to use any of these features (i.e. with settings different than | |||
the above), that is not a problem. However, GitHub will create the default | |||
"master" branch for you. In that case, clone the repository locally and | |||
follow the steps in the <a href="#simple-migration"><strong>Simple Migration</strong></a> section | |||
instead.</p> | |||
</li> | |||
<li> | |||
<p>Initialize an empty Git repository:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ mkdir my-git-project | |||
$ <span class="pl-c1">cd</span> my-git-project | |||
$ git init <span class="pl-c1">.</span></pre></div> | |||
</li> | |||
<li> | |||
<p>Create the "main" branch:</p> | |||
</li> | |||
<li> | |||
<p>Work on your project and commit some changes. For example, add a README:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ <span class="pl-c1">echo</span> <span class="pl-s"><span class="pl-pds">"</span># My Git Project<span class="pl-pds">"</span></span> <span class="pl-k">>></span> README.md | |||
$ git add README.md | |||
$ git commit -m <span class="pl-s"><span class="pl-pds">"</span>Initial commit<span class="pl-pds">"</span></span></pre></div> | |||
</li> | |||
<li> | |||
<p>Push your commits to GitHub:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ git remote add origin https://github.com/your-username/my-git-project.git | |||
$ git push -u origin main</pre></div> | |||
</li> | |||
</ol> | |||
<p>That's all! Since "main" was the first branch you pushed to GitHub, it will be | |||
set correctly as the default branch. We also never committed any changes to the | |||
"master" branch locally, it effectively never existed so there is nothing left | |||
to clean up. Enjoy your new project!</p> | |||
<h2><a id="user-content-simple-migration" class="anchor" aria-hidden="true" href="#simple-migration"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Simple Migration</h2> | |||
<p>If you have a small personal project and you are comfortable with just doing | |||
the rename right away, here are the steps you can take.</p> | |||
<p>Note that if this is a <a href="https://pages.github.com">GitHub Pages</a> repository and | |||
the content is stored on the "master" branch, then you cannot perform the | |||
migration at this time since GitHub Pages does not seem to support alternative | |||
default branch names yet. If you want, you may follow the steps in the <a href="#local-migration"><strong>Local | |||
Migration</strong></a> or <a href="#gradual-migration"><strong>Gradual Migration</strong></a> | |||
section partially to get your project ready.</p> | |||
<ol> | |||
<li> | |||
<p>Pull the latest commits from the "master" branch into your local repository:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ <span class="pl-c1">cd</span> my-git-project | |||
$ git checkout master | |||
$ git pull origin master</pre></div> | |||
</li> | |||
<li> | |||
<p>Rename the local "master" branch to "main":</p> | |||
</li> | |||
<li> | |||
<p>Push the "main" branch to GitHub:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ git push -u origin main</pre></div> | |||
</li> | |||
<li> | |||
<p><a href="https://help.github.com/en/github/administering-a-repository/setting-the-default-branch">Change the default branch on GitHub</a> to "main".</p> | |||
</li> | |||
<li> | |||
<p>If there are existing pull requests open against the "master" branch that | |||
you would like to keep, <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/changing-the-base-branch-of-a-pull-request">update their base branch</a> to | |||
the "main" branch. Otherwise, they will be closed automatically when we | |||
delete the remote "master" branch on GitHub.</p> | |||
</li> | |||
<li> | |||
<p>Delete your local "master" branch:</p> | |||
</li> | |||
<li> | |||
<p>Delete the remote "master" branch:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ git push origin :master</pre></div> | |||
</li> | |||
</ol> | |||
<p>At this point, the migration is complete. However, as you work on the project, | |||
you may discover additional settings that you need to tweak to account for the | |||
rename. For example, you may have update the branch names in your CI config.</p> | |||
<h2><a id="user-content-gradual-migration" class="anchor" aria-hidden="true" href="#gradual-migration"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Gradual Migration</h2> | |||
<p>If you have a work or open-source repository with multiple contributors and | |||
forks, you may prefer to perform the migration gradually.</p> | |||
<p>These steps are for you if you find yourself in a similar scenario, where it is | |||
important to give everyone ample of time to prepare for the migration, changing | |||
local configs, adapting workflows, scripts and other automation to ensure a | |||
seamless migration.</p> | |||
<p>This gradual migration plan is intended to be spread out over a long period of | |||
time – weeks, or months. It uses all available tools on GitHub to provide as | |||
much advance notice as possible.</p> | |||
<p>For most organizations, this plan may be overly cautious and some of the steps | |||
may not be necessary. On the other hand, for a popular open-source project, it | |||
may not be feasible to get to the end and fully deprecate and remove the legacy | |||
"master" branch at all, due to compatibility requirements. Treat this plan as a | |||
template and adapt it for your own needs.</p> | |||
<p>Unlike the other sections, the steps here are a bit less exact and is intended | |||
for someone with a some prior experience with Git and GitHub. In practice, you | |||
will probably run into situations that causes deviations from the plan which | |||
would require some manual repair and adjustments. For example, pushes during a | |||
partial GitHub outage may cause the two branches to diverge and requires you | |||
to determine how to best reconcile the differences.</p> | |||
<h3><a id="user-content-phase-1-mirror-master-and-main" class="anchor" aria-hidden="true" href="#phase-1-mirror-master-and-main"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Phase 1: Mirror "master" and "main"</h3> | |||
<p>The goal of this phase is to make it <em>possible</em> to use the "main" branch name | |||
as an alternative. This allows some early adopters to start testing the new | |||
setup.</p> | |||
<ol> | |||
<li> | |||
<p>As always, make sure your local "master" branch is up-to-date.</p> | |||
</li> | |||
<li> | |||
<p>Create the new "main" branch:</p> | |||
</li> | |||
<li> | |||
<p>Add a <a href="https://github.com/features/actions">GitHub Actions</a> workflow file at | |||
<strong>.github/workflows/mirror-master-and-main.yml</strong> with the following:</p> | |||
<div class="highlight highlight-source-yaml"><pre><span class="pl-ent">name</span>: <span class="pl-s">Mirror "master" and "main" branches</span> | |||
<span class="pl-ent">on</span>: | |||
<span class="pl-ent">push</span>: | |||
<span class="pl-ent">branches</span>: | |||
- <span class="pl-s">master</span> | |||
- <span class="pl-s">main</span> | |||
<span class="pl-ent">jobs</span>: | |||
<span class="pl-ent">mirror</span>: | |||
<span class="pl-ent">runs-on</span>: <span class="pl-s">ubuntu-latest</span> | |||
<span class="pl-ent">steps</span>: | |||
- <span class="pl-ent">name</span>: <span class="pl-s">Mirror to "master"</span> | |||
<span class="pl-ent">uses</span>: <span class="pl-s">zofrex/mirror-branch@v1</span> | |||
<span class="pl-ent">with</span>: | |||
<span class="pl-ent">target-branch</span>: <span class="pl-s">master</span> | |||
<span class="pl-ent">force</span>: <span class="pl-c1">false</span> | |||
- <span class="pl-ent">name</span>: <span class="pl-s">Mirror to "main"</span> | |||
<span class="pl-ent">uses</span>: <span class="pl-s">zofrex/mirror-branch@v1</span> | |||
<span class="pl-ent">with</span>: | |||
<span class="pl-ent">target-branch</span>: <span class="pl-s">main</span> | |||
<span class="pl-ent">force</span>: <span class="pl-c1">false</span></pre></div> | |||
</li> | |||
<li> | |||
<p>Commit and your changes to the local "main" branch.</p> | |||
</li> | |||
<li> | |||
<p>Push your changes to the remote "main" branch:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ git push -u origin main</pre></div> | |||
</li> | |||
</ol> | |||
<p>If things are working correctly, you should see the same commit pushed to the | |||
"master" branch shortly. You can monitor the progress and unexpected errors in | |||
the "Actions" tab in your repository.</p> | |||
<h4><a id="user-content-about-github-actions" class="anchor" aria-hidden="true" href="#about-github-actions"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>About GitHub Actions</h4> | |||
<p>You do not have to be already using GitHub Actions for this to work. You do not | |||
need to activate or enable the feature for your repository, simply pushing the | |||
workflow file to the is sufficient. All open-source repositories have unlimited | |||
GitHub Actions minutes, and all personal and team accounts comes with 2000-3000 | |||
free GitHub Actions minutes for private repositories.</p> | |||
<p>If you already regularly uses up your free minutes, this may slightly increase | |||
your GitHub bills, but in practice, the workflow we added runs very quickly so | |||
the impact is very minimal. For reference, GitHub Actions are billed at $0.008 | |||
USD per minute for private repositories, after the free quota is exhausted.</p> | |||
<p>This workflow will be triggered when commits are pushed to either the "master" | |||
or "main" branch. It uses the <a href="https://github.com/marketplace/actions/mirror-branch">Mirror Branch action</a> to | |||
update the branches using GitHub's API.</p> | |||
<h4><a id="user-content-interaction-with-branch-protection" class="anchor" aria-hidden="true" href="#interaction-with-branch-protection"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Interaction with Branch Protection</h4> | |||
<p>Unfortunately, if you have enabled <a href="https://help.github.com/en/github/administering-a-repository/configuring-protected-branches">branch protection</a> on | |||
the "master" branch, the push from the mirroring action may be rejected. For | |||
example, if you had enabled "Require pull request reviews before merging", then | |||
this would not work as the changes are expected to be submitted via a pull | |||
request with reviews.</p> | |||
<p>A possible workaround is to disable the "Include administrators" checkbox in | |||
the branch protection settings for the "master" branch and configure the script | |||
to push the commits as an administrator:</p> | |||
<ol> | |||
<li> | |||
<p>Login as an administrator on GitHub. You may also want to consider creating | |||
a new account specifically for this purpose.</p> | |||
</li> | |||
<li> | |||
<p>Generate a <a href="https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line">personal access token</a> with the "repo" | |||
scope (and the "public_repo" scope, if needed).</p> | |||
</li> | |||
<li> | |||
<p><a href="https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets-for-a-repository">Add it as a secret</a> to the repository.</p> | |||
</li> | |||
<li> | |||
<p>Change the "Checkout" step in the mirror workflow to use the new deploy key:</p> | |||
<div class="highlight highlight-source-yaml"><pre>- <span class="pl-ent">name</span>: <span class="pl-s">Checkout</span> | |||
<span class="pl-ent">uses</span>: <span class="pl-s">actions/checkout@v2</span> | |||
<span class="pl-ent">with</span>: | |||
<span class="pl-ent">token</span>: <span class="pl-s">${{ secrets.DEPLOY_TOKEN }}</span></pre></div> | |||
<p>Here, <code>DEPLOY_TOKEN</code> is the name you picked from step 3.</p> | |||
</li> | |||
</ol> | |||
<p>Alternatively, an SSH key for the administrator can be used instead of a | |||
personal access token, via the <code>ssh-key</code> argument. See the documentation for | |||
the <a href="https://github.com/actions/checkout">checkout action</a> for more details.</p> | |||
<h4><a id="user-content-interaction-with-other-github-action-workflows" class="anchor" aria-hidden="true" href="#interaction-with-other-github-action-workflows"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Interaction with Other GitHub Action Workflows</h4> | |||
<p>By default, when pushing commits from within the GitHub Actions job, it does | |||
not trigger additional GitHub Actions workflow to run. For example, when a | |||
contributor pushes to the "main" branch, it will trigger any GitHub Actions | |||
that normally runs on the "main" branch's push events, including the one we | |||
added here. However, when our mirror workflow pushes the same commit to the | |||
"master" branch, it will not trigger any workflow that normally runs on the | |||
"master" branch's push events.</p> | |||
<p>For this reason, you may want to update existing workflows that runs on the | |||
"master" branch to also run on the "main" branch, as we did in our mirror | |||
workflow file (the <code>on.push.branches</code> config key). This is the recommended | |||
approach as it ensures only a single build per push.</p> | |||
<p>Alternatively, if it is important to you that workflows are triggered by pushes | |||
from the mirror workflow, you can accomplish this by supplying an alternative | |||
SSH key to the <a href="https://github.com/actions/checkout">checkout action</a>:</p> | |||
<ol> | |||
<li> | |||
<p><a href="https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent">Generate a new SSH key</a> locally. Don't worry about adding | |||
it to the ssh-agent.</p> | |||
</li> | |||
<li> | |||
<p>Find the generated <em>public key</em> and <a href="https://developer.github.com/v3/guides/managing-deploy-keys/#deploy-keys">add it as a deploy key</a> | |||
to the repository. Be sure to select "Allow write access".</p> | |||
</li> | |||
<li> | |||
<p>Find the generated <em>private key</em> and <a href="https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets-for-a-repository">add it as a secret</a> to the | |||
repository.</p> | |||
</li> | |||
<li> | |||
<p>Change the "Checkout" step in the mirror workflow to use the new deploy key:</p> | |||
<div class="highlight highlight-source-yaml"><pre>- <span class="pl-ent">name</span>: <span class="pl-s">Checkout</span> | |||
<span class="pl-ent">uses</span>: <span class="pl-s">actions/checkout@v2</span> | |||
<span class="pl-ent">with</span>: | |||
<span class="pl-ent">ssh-key</span>: <span class="pl-s">${{ secrets.DEPLOY_KEY }}</span></pre></div> | |||
<p>Here, <code>DEPLOY_KEY</code> is the name you picked from step 3.</p> | |||
</li> | |||
</ol> | |||
<p>With this, the mirror workflow will authenticate with GitHub using the deploy | |||
key instead of the default token when pushing commits, triggering any workflows | |||
as if a regular user had pushed those commits. This does not change the author | |||
or committer on the commits.</p> | |||
<h4><a id="user-content-real-world-example" class="anchor" aria-hidden="true" href="#real-world-example"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Real World Example</h4> | |||
<p>See <a href="https://github.com/chancancode/ember-concurrency-async/commit/afbacf7088e473dd056138109e00d8749b95b2d0">this commit</a> and <a href="https://github.com/chancancode/ember-concurrency-async/runs/788797792?check_suite_focus=true">the resulting workflow run</a> | |||
for an example of this working in action. Note that the code in the commit may | |||
be outdated by the time you read this – refer to the above for the latest | |||
instructions.</p> | |||
<h4><a id="user-content-next-steps" class="anchor" aria-hidden="true" href="#next-steps"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Next Steps</h4> | |||
<p>After verifying that everything is working as intended, you can start inviting | |||
the early adopters to start pushing to the "main" branch. The easiest way to do | |||
this is to rename the local "master" branch:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ <span class="pl-c1">cd</span> my-git-project | |||
$ git checkout master | |||
$ git branch -m main | |||
$ git branch -u origin/main</pre></div> | |||
<p>This would also be a good time to start changing any automation or external | |||
services to the "main" branch to ensure that everything is working as expected.</p> | |||
<h3><a id="user-content-phase-2-change-the-default-branch-to-main-deprecate-master" class="anchor" aria-hidden="true" href="#phase-2-change-the-default-branch-to-main-deprecate-master"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Phase 2: Change the default branch to "main", deprecate "master"</h3> | |||
<p>After verifying the viability of the rename during the previous phase, the goal | |||
of this phase is to set "main" as the default branch and start issuing | |||
deprecation warnings when the legacy "master" branch is used.</p> | |||
<ol> | |||
<li> | |||
<p><a href="https://help.github.com/en/github/administering-a-repository/setting-the-default-branch">Change the default branch on GitHub</a> to "main".</p> | |||
</li> | |||
<li> | |||
<p>Add a <a href="https://github.com/features/actions">GitHub Actions</a> workflow file at | |||
<strong>.github/workflows/deprecate-master-branch.yml</strong> with the following:</p> | |||
<div class="highlight highlight-source-yaml"><pre><span class="pl-ent">name</span>: <span class="pl-s">Deprecate "master" branch</span> | |||
<span class="pl-ent">on</span>: | |||
<span class="pl-ent">push</span>: | |||
<span class="pl-ent">branches</span>: | |||
- <span class="pl-s">master</span> | |||
<span class="pl-ent">pull_request</span>: | |||
<span class="pl-ent">branches</span>: | |||
- <span class="pl-s">master</span> | |||
<span class="pl-ent">jobs</span>: | |||
<span class="pl-ent">on-push</span>: | |||
<span class="pl-ent">runs-on</span>: <span class="pl-s">ubuntu-latest</span> | |||
<span class="pl-ent">if</span>: <span class="pl-s">${{ github.event_name == 'push' }}</span> | |||
<span class="pl-ent">steps</span>: | |||
- <span class="pl-ent">name</span>: <span class="pl-s">Deprecation</span> | |||
<span class="pl-ent">uses</span>: <span class="pl-s">peter-evans/commit-comment@v1</span> | |||
<span class="pl-ent">with</span>: | |||
<span class="pl-ent">body</span>: <span class="pl-s">|</span> | |||
<span class="pl-s"> Hello @${{ github.event.sender.login }}!</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> I see that you have pushed some commits to the "master" branch. We are in the process of renaming the "master" branch to "main" in this repository.</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> :warning: **The "master" branch is deprecated and will be removed from this repository in the future.**</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> Please migrate your local repository by renaming the "master" branch to "main":</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> ```bash</span> | |||
<span class="pl-s"> $ cd my-git-project</span> | |||
<span class="pl-s"> $ git checkout master</span> | |||
<span class="pl-s"> $ git branch -m main</span> | |||
<span class="pl-s"> $ git branch -u origin/main</span> | |||
<span class="pl-s"> ```</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> Before merging pull requests, ensure their base branch is set to "main" instead of "master". For more information on how to do this, refer to [this GitHub support article][1].</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> [1]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/changing-the-base-branch-of-a-pull-request</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"/> <span class="pl-ent">on-pull-request</span>: | |||
<span class="pl-ent">runs-on</span>: <span class="pl-s">ubuntu-latest</span> | |||
<span class="pl-ent">if</span>: <span class="pl-s">${{ github.event_name == 'pull_request' }}</span> | |||
<span class="pl-ent">env</span>: | |||
<span class="pl-ent">DEPRECATION_MESSAGE</span>: <span class="pl-s">|</span> | |||
<span class="pl-s"> Hello @${{ github.event.sender.login }}!</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> I see that you have opened a pull request against the "master" branch. We are in the process of renaming the "master" branch to "main" in this repository.</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> :warning: **The "master" branch is deprecated and will be removed from this repository in the future.**</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> Please migrate your local repository by renaming the "master" branch to "main":</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> ```bash</span> | |||
<span class="pl-s"> $ cd my-git-project</span> | |||
<span class="pl-s"> $ git checkout master</span> | |||
<span class="pl-s"> $ git branch -m main</span> | |||
<span class="pl-s"> $ git branch -u origin/main</span> | |||
<span class="pl-s"> ```</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> Please also set the base branch for this pull request to "main" instead of "master". For more information on how to do this, refer to [this GitHub support article][1].</span> | |||
<span class="pl-s"/> | |||
<span class="pl-s"> [1]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/changing-the-base-branch-of-a-pull-request</span> | |||
<span class="pl-s"/> <span class="pl-ent">steps</span>: | |||
- <span class="pl-ent">name</span>: <span class="pl-s">Deprecation</span> | |||
<span class="pl-ent">if</span>: <span class="pl-s">${{ github.event.pull_request.head.repo.fork == false }}</span> | |||
<span class="pl-ent">uses</span>: <span class="pl-s">peter-evans/create-or-update-comment@v1</span> | |||
<span class="pl-ent">with</span>: | |||
<span class="pl-ent">issue-number</span>: <span class="pl-s">${{ github.event.number }}</span> | |||
<span class="pl-ent">body</span>: <span class="pl-s">${{ env.DEPRECATION_MESSAGE }}</span> | |||
- <span class="pl-ent">name</span>: <span class="pl-s">Deprecation</span> | |||
<span class="pl-ent">if</span>: <span class="pl-s">${{ github.event.pull_request.head.repo.fork == true }}</span> | |||
<span class="pl-ent">run</span>: <span class="pl-s">|</span> | |||
<span class="pl-s"> echo "$DEPRECATION_MESSAGE"</span> | |||
<span class="pl-s"> echo '::error::Please set the base branch for this pull request to "main" instead of "master".'</span> | |||
<span class="pl-s"> exit 1</span></pre></div> | |||
</li> | |||
<li> | |||
<p>Commit and push your changes to the "main" branch.</p> | |||
</li> | |||
</ol> | |||
<p>We added a workflow file that triggers whenever a contributor pushes to or | |||
opens a pull request against the "master" branch.</p> | |||
<p>The workflow adds a comment to the commit or pull request, notifying the | |||
contributor that the "master" branch has been deprecated, along with the steps | |||
they need to take to migrate their local repository and changes they need to | |||
make it to the pull request.</p> | |||
<p>It is recommended that you customize the messages with additional information | |||
relevant for your organization. For example, you may want to include a link to | |||
a tracking issue for additional context, or ways for the contributor to ask for | |||
additional assistance if needed.</p> | |||
<h4><a id="user-content-limitations-of-github-actions-in-forks" class="anchor" aria-hidden="true" href="#limitations-of-github-actions-in-forks"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Limitations of GitHub Actions in Forks</h4> | |||
<p>Unfortunately, due to limitations of GitHub Actions, it is not possible to add | |||
a pull request comment from the workflow when the pull request originated from | |||
a fork, which is very common in open-source repositories. As a workaround, the | |||
workflow prints the deprecation message to the logs and fails the build.</p> | |||
<h4><a id="user-content-real-world-example-1" class="anchor" aria-hidden="true" href="#real-world-example-1"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Real World Example</h4> | |||
<p>See <a href="https://github.com/chancancode/ember-concurrency-async/commit/7f3509b4363f3fcdb3275ec136c4b5766f39c192">this commit</a> and <a href="https://github.com/chancancode/ember-concurrency-async/pull/5">this pull request</a> for an | |||
example of this working in action. Note that the code in the commit may be | |||
outdated by the time you read this – refer to the above for the latest | |||
instructions.</p> | |||
<h4><a id="user-content-next-steps-1" class="anchor" aria-hidden="true" href="#next-steps-1"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Next Steps</h4> | |||
<p>This would be a good time to start updating any internal and external links to | |||
the "master" branch. A common example would be automatically generated links to | |||
source code from the API documentation.</p> | |||
<h3><a id="user-content-phase-3-complete-the-migration" class="anchor" aria-hidden="true" href="#phase-3-complete-the-migration"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Phase 3: Complete the migration</h3> | |||
<p>After a successful phase 2 rollout, it is time to plan for completing the | |||
migration. However, what completion means is going to be different depending on | |||
your situation.</p> | |||
<p>For private work repositories, the legacy "master" branch can likely be removed | |||
from the repository after giving team members a few weeks to migrate. Don't | |||
forget to remove the workflow files as well.</p> | |||
<p>For open-source repositories with lots of contributors, you may want to move a | |||
lot slower. Monitor the Actions tab of the repository to see how often the | |||
deprecation workflow is triggered. When the activity diminishes, it may be good | |||
indication that the legacy "master" branch is no longer needed.</p> | |||
<h4><a id="user-content-soft-removal" class="anchor" aria-hidden="true" href="#soft-removal"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Soft Removal</h4> | |||
<p>As an alternative to removing the branch right away, you may want to consider | |||
pushing a final commit to the branch, removing all files but leave behind a | |||
README file explaining that branch has been moved, along with the steps they | |||
need to take in order to migrate their local repository.</p> | |||
<h4><a id="user-content-url-considerations" class="anchor" aria-hidden="true" href="#url-considerations"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>URL Considerations</h4> | |||
<p>It is also important to consider URL breakages, as links that points to the | |||
files on the "master" branch will stop working once the branch is removed, | |||
including with the soft-removal method described above.</p> | |||
<p>The impact of this has to be evaluated contextually, but it is important to | |||
note that the scope of the breakage is fairly limited, as this only directly | |||
impacts URLs that links to the "master" branch directly. Links pointing to the | |||
active development branch of repository is quite fragile (especially with line | |||
numbers) and often breaks for other reasons.</p> | |||
<p>For example, a refactor that moves around files or switching from JavaScript to | |||
TypeScript would invalidate these URLs. This sort of activity is fairly common | |||
on an active code repository and is usually performed without taking the URL | |||
consideration in mind. For this reason, it is considered a best practice to use | |||
SHA-based <a href="https://help.github.com/en/github/managing-files-in-a-repository/getting-permanent-links-to-files">permanent links</a> in most situations. These links | |||
are unaffected by the branch rename.</p> | |||
<h4><a id="user-content-packages-considerations" class="anchor" aria-hidden="true" href="#packages-considerations"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Packages Considerations</h4> | |||
<p>For repositories containing <em>installable packages</em>, there are some additional | |||
considerations. Many package managers allow for installing packages from a Git | |||
repository. For example, in npm and yarn, dependencies can be a string like | |||
"username/repo" or "username/repo#branch" in lieu of version range. Likewise, | |||
GitHub Actions are installed using repository and branch references, and it is | |||
a relatively common practice to point an action at the "master" branch.</p> | |||
<p>In these cases, the decision on whether to remove the legacy "master" branch | |||
has to be made carefully. Here are some examples of things to investigate | |||
and consider:</p> | |||
<ul> | |||
<li> | |||
<p>When the branch is omitted from the specifier (e.g. "username/repo"), does | |||
the package manager in your ecosystem hard-code the default to "master" on | |||
the client, or does it respect the remote HEAD ref?</p> | |||
</li> | |||
<li> | |||
<p>Does the package manager use a lockfile, and if so, does it serialize the | |||
branch name (as opposed to the resolved SHA) into the lockfile?</p> | |||
</li> | |||
<li> | |||
<p>Does the package manager maintain a cache of cloned repositories, and if so | |||
do they recover gracefully to a remote branch disappearing?</p> | |||
</li> | |||
</ul> | |||
<p>The answer to these questions affects the potential impact to your end-users | |||
if the legacy "master" branch is removed from the repository. For some, the | |||
end-state of the migration may be to keep the "master" branch permanently as a | |||
read-only mirror, or it may be sufficient to freeze the branch's content and | |||
stop providing updates there. For others, the potential breakage maybe small | |||
enough that it is can be easily justified.</p> | |||
<p>While the workflows added in phase 2 are effective for deprecating <em>writes</em> to | |||
the legacy "master" branch. Unfortunately, Git and GitHub do not offer the | |||
ability to do the same for <em>reads</em> to the branch.</p> | |||
<p>However, you may be able to use features from the package manager to accomplish | |||
a similar result. For example, instead of mirroring the "main" branch to the | |||
"master" branch exactly, you could add a post-install hook to the version on | |||
"master" to issue the deprecation message for any potential consumers.</p> | |||
<h4><a id="user-content-a-concrete-example" class="anchor" aria-hidden="true" href="#a-concrete-example"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>A Concrete Example</h4> | |||
<p>Using the Node.js ecosystem as an example, we can put these considerations into | |||
context, based on preliminary testing with npm and yarn classic (v1). If you | |||
found different results in your own testing, or with other package managers | |||
(pnpm, yarn v2, etc), please file an issue here.</p> | |||
<ul> | |||
<li> | |||
<p>The popular package managers in the ecosystem support installing packages | |||
from git, by specifying "username/repo" or "username/repo#branch" in the | |||
dependencies section of package.json.</p> | |||
</li> | |||
<li> | |||
<p>When a branch name is not specified, the popular package managers defaults to | |||
the remote HEAD ref, which is set by the default branch on GitHub, instead of | |||
hardcoding to the "master" branch in the client.</p> | |||
</li> | |||
<li> | |||
<p>The popular package managers uses a lockfile by default. They serialize the | |||
resolved SHA into the lockfiles, as long as the commits referred to by these | |||
SHAs remain reachable on the remote repository, they will install just fine | |||
when using a lockfile. In the case of a branch rename, this is not an issue, | |||
as the history and commits will remain intact.</p> | |||
</li> | |||
<li> | |||
<p>When installing without a lockfile, the popular package managers will fetch | |||
the latest commit from the repository. Renaming the remote branch did not | |||
appear to cause any issues, either because the repositories are not cached, | |||
or the clients are able to recover gracefully from a "missing" remote branch.</p> | |||
</li> | |||
<li> | |||
<p>Post-install hooks are supported. However, yarn classic <a href="https://github.com/yarnpkg/yarn/issues/5476">hides the output | |||
produced by these scripts</a> if | |||
they are successful (exit cleanly with exit code 0). However, when they fail, | |||
they output <em>is</em> shown to the user.</p> | |||
</li> | |||
<li> | |||
<p>Generally speaking, the ecosystem has strong norms and expectations around | |||
adhering to <a href="https://semver.org" rel="nofollow">semantic versioning</a>. Usually, breaking changes are only | |||
expected on major version bumps.</p> | |||
</li> | |||
<li> | |||
<p>By using a Git dependency instead of specifying a semver range, they are | |||
explicitly opting out of the normal semver guarantee, and breakages are to be | |||
expected. No one could reasonably expect that pointing a dependency to the | |||
active development branch without using a lockfile will result in a stable | |||
system.</p> | |||
</li> | |||
</ul> | |||
<p>Given these findings, here is a concrete proposal for a maximally graceful | |||
completion plan:</p> | |||
<ol> | |||
<li> | |||
<p>Stop providing updates to the "master" branch by removing the mirroring | |||
workflow added in phase 1.</p> | |||
</li> | |||
<li> | |||
<p>Push a commit the "master" branch, updating the README as well as adding a | |||
deprecation message to the runtime code (the <code>main</code> entry point):</p> | |||
<div class="highlight highlight-source-js"><pre><span class="pl-c">// index.js</span> | |||
<span class="pl-k">let</span> <span class="pl-s1">command</span> <span class="pl-c1">=</span> <span class="pl-s">'npm update my-git-project'</span><span class="pl-kos">;</span> | |||
<span class="pl-k">if</span> <span class="pl-kos">(</span><span class="pl-s1">process</span><span class="pl-kos">.</span><span class="pl-c1">env</span><span class="pl-kos">.</span><span class="pl-c1">npm_execpath</span> <span class="pl-c1">&&</span> <span class="pl-s1">process</span><span class="pl-kos">.</span><span class="pl-c1">env</span><span class="pl-kos">.</span><span class="pl-c1">npm_execpath</span><span class="pl-kos">.</span><span class="pl-en">indexOf</span><span class="pl-kos">(</span><span class="pl-s">'yarn'</span><span class="pl-kos">)</span> !== <span class="pl-c1">-</span><span class="pl-c1">1</span><span class="pl-kos">)</span> <span class="pl-kos">{</span> | |||
<span class="pl-s1">command</span> <span class="pl-c1">=</span> <span class="pl-s">'yarn upgrade my-git-project'</span><span class="pl-kos">;</span> | |||
<span class="pl-kos">}</span> | |||
<span class="pl-smi">console</span><span class="pl-kos">.</span><span class="pl-en">warn</span><span class="pl-kos">(</span> | |||
<span class="pl-s">`You are running a deprecated copy of the "my-git-project" installed `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`from the "master" branch of our repository. The "master" branch is `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`deprecated and no longer receives any updates. The branch will soon `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`be removed from our repository, at which point the package will fail `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`to install.\n\n`</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`To fix this issue, please modify your package.json and change the `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`"my-git-project" dependency from "my-repo/my-git-project#master" to `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`"my-repo/my-git-project" or a valid semver range. After making the `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`change, run "<span class="pl-s1"><span class="pl-kos">${</span><span class="pl-s1">command</span><span class="pl-kos">}</span></span>" to update the package.`</span> | |||
<span class="pl-kos">)</span><span class="pl-kos">;</span> | |||
<span class="pl-c">// ...rest of index.js</span></pre></div> | |||
</li> | |||
<li> | |||
<p>When releasing the next major version of the package, push another commit to | |||
the "master" branch, remove all files from the branch, leaving behind only a | |||
minimal README file, package.json and index.js:</p> | |||
<div class="highlight highlight-source-js"><pre><span class="pl-c">// package.json</span> | |||
<span class="pl-kos">{</span> | |||
<span class="pl-s">"name"</span>: <span class="pl-s">"my-git-project"</span><span class="pl-kos">,</span> | |||
<span class="pl-s">"scripts"</span>: <span class="pl-kos">{</span> | |||
<span class="pl-s">"postinstall"</span>: <span class="pl-s">"node index.js"</span> | |||
<span class="pl-kos">}</span> | |||
<span class="pl-kos">}</span></pre></div> | |||
<div class="highlight highlight-source-js"><pre><span class="pl-c">// index.js</span> | |||
<span class="pl-k">let</span> <span class="pl-s1">command</span> <span class="pl-c1">=</span> <span class="pl-s">'npm update my-git-project'</span><span class="pl-kos">;</span> | |||
<span class="pl-k">if</span> <span class="pl-kos">(</span><span class="pl-s1">process</span><span class="pl-kos">.</span><span class="pl-c1">env</span><span class="pl-kos">.</span><span class="pl-c1">npm_execpath</span> <span class="pl-c1">&&</span> <span class="pl-s1">process</span><span class="pl-kos">.</span><span class="pl-c1">env</span><span class="pl-kos">.</span><span class="pl-c1">npm_execpath</span><span class="pl-kos">.</span><span class="pl-en">indexOf</span><span class="pl-kos">(</span><span class="pl-s">'yarn'</span><span class="pl-kos">)</span> !== <span class="pl-c1">-</span><span class="pl-c1">1</span><span class="pl-kos">)</span> <span class="pl-kos">{</span> | |||
<span class="pl-s1">command</span> <span class="pl-c1">=</span> <span class="pl-s">'yarn upgrade my-git-project'</span><span class="pl-kos">;</span> | |||
<span class="pl-kos">}</span> | |||
<span class="pl-smi">console</span><span class="pl-kos">.</span><span class="pl-en">error</span><span class="pl-kos">(</span> | |||
<span class="pl-s">`You have installed "my-git-project" from the "master" branch of our `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`repository. The "master" branch has been official retired.\n\n`</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`To fix this issue, please modify your package.json and change the `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`"my-git-project" dependency from "my-repo/my-git-project#master" to `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`"my-repo/my-git-project" or a valid semver range. After making the `</span> <span class="pl-c1">+</span> | |||
<span class="pl-s">`change, run "<span class="pl-s1"><span class="pl-kos">${</span><span class="pl-s1">command</span><span class="pl-kos">}</span></span>" to update the package.`</span> | |||
<span class="pl-kos">)</span><span class="pl-kos">;</span> | |||
<span class="pl-s1">process</span><span class="pl-kos">.</span><span class="pl-en">exit</span><span class="pl-kos">(</span><span class="pl-c1">1</span><span class="pl-kos">)</span><span class="pl-kos">;</span></pre></div> | |||
</li> | |||
<li> | |||
<p>After some time, the master branch can be removed from the repository. This | |||
does not constitute a breaking change, as the package already ceased to | |||
function as of the previous commit. It was just a courteous message to ease | |||
confusion and provide actionable instructions for fixing the issue.</p> | |||
</li> | |||
</ol> | |||
<p>For most projects and organizations, this amount of notice is probably not | |||
necessary or warranted, but it showcases the available tools and techniques, | |||
and demonstrates that there can be a good migration path even under very strict | |||
compatibility requirements. As always, use these steps as a template and tailor | |||
them to your own needs.</p> | |||
<h2><a id="user-content-local-migration" class="anchor" aria-hidden="true" href="#local-migration"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>Local Migration</h2> | |||
<p>Finally, if you are working on a repository you don't control, and you would | |||
like to refer to your local branch with a different name without making any | |||
changes to the upstream project, you can rename your local "master" branch to | |||
"main" with these steps:</p> | |||
<div class="highlight highlight-source-shell"><pre>$ <span class="pl-c1">cd</span> my-git-project | |||
$ git checkout master | |||
$ git branch -m main | |||
$ git branch -u origin/master</pre></div> | |||
<p>This renames the local branch to "main" but sets the remote tracking branch to | |||
"master".</p> | |||
<h2><a id="user-content-license" class="anchor" aria-hidden="true" href="#license"><svg class="octicon octicon-link" viewbox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"/></svg></a>License</h2> | |||
<p>This content in this repository, including this documentation and code examples | |||
are licensed under the <a href="https://creativecommons.org/share-your-work/public-domain/cc0/" rel="nofollow">CC0 "No Rights Reserved"</a> public domain | |||
license. Feel free to reproduce and adapt this work into your own proposals, | |||
documentation, etc.</p> | |||
<p>Attribution is not necessary. However, this guide receives constant updates to | |||
reflect current best-practice and solutions based implementation feedback, so | |||
a reference to this repository may be helpful.</p> |
@@ -0,0 +1,159 @@ | |||
<!doctype html><!-- This is a valid HTML5 document. --> | |||
<!-- Screen readers, SEO, extensions and so on. --> | |||
<html lang="fr"> | |||
<!-- Has to be within the first 1024 bytes, hence before the <title> | |||
See: https://www.w3.org/TR/2012/CR-html5-20121217/document-metadata.html#charset --> | |||
<meta charset="utf-8"> | |||
<!-- Why no `X-UA-Compatible` meta: https://stackoverflow.com/a/6771584 --> | |||
<!-- The viewport meta is quite crowded and we are responsible for that. | |||
See: https://codepen.io/tigt/post/meta-viewport-for-2015 --> | |||
<meta name="viewport" content="width=device-width,initial-scale=1"> | |||
<!-- Required to make a valid HTML5 document. --> | |||
<title>The end of the Redis adventure (archive) — David Larlet</title> | |||
<!-- That good ol' feed, subscribe :). --> | |||
<link rel="alternate" type="application/atom+xml" title="Feed" href="/david/log/"> | |||
<!-- Generated from https://realfavicongenerator.net/ such a mess. --> | |||
<link rel="apple-touch-icon" sizes="180x180" href="/static/david/icons2/apple-touch-icon.png"> | |||
<link rel="icon" type="image/png" sizes="32x32" href="/static/david/icons2/favicon-32x32.png"> | |||
<link rel="icon" type="image/png" sizes="16x16" href="/static/david/icons2/favicon-16x16.png"> | |||
<link rel="manifest" href="/static/david/icons2/site.webmanifest"> | |||
<link rel="mask-icon" href="/static/david/icons2/safari-pinned-tab.svg" color="#07486c"> | |||
<link rel="shortcut icon" href="/static/david/icons2/favicon.ico"> | |||
<meta name="msapplication-TileColor" content="#f0f0ea"> | |||
<meta name="msapplication-config" content="/static/david/icons2/browserconfig.xml"> | |||
<meta name="theme-color" content="#f0f0ea"> | |||
<!-- Documented, feel free to shoot an email. --> | |||
<link rel="stylesheet" href="/static/david/css/style_2020-06-19.css"> | |||
<!-- See https://www.zachleat.com/web/comprehensive-webfonts/ for the trade-off. --> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_regular.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_bold.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_italic.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_regular.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_bold.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_italic.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin> | |||
<script type="text/javascript"> | |||
function toggleTheme(themeName) { | |||
document.documentElement.classList.toggle( | |||
'forced-dark', | |||
themeName === 'dark' | |||
) | |||
document.documentElement.classList.toggle( | |||
'forced-light', | |||
themeName === 'light' | |||
) | |||
} | |||
const selectedTheme = localStorage.getItem('theme') | |||
if (selectedTheme !== 'undefined') { | |||
toggleTheme(selectedTheme) | |||
} | |||
</script> | |||
<meta name="robots" content="noindex, nofollow"> | |||
<meta content="origin-when-cross-origin" name="referrer"> | |||
<!-- Canonical URL for SEO purposes --> | |||
<link rel="canonical" href="http://antirez.com/news/133"> | |||
<body class="remarkdown h1-underline h2-underline h3-underline hr-center ul-star pre-tick"> | |||
<article> | |||
<h1>The end of the Redis adventure</h1> | |||
<nav> | |||
<p class="center"> | |||
<a href="/david/" title="Aller à l’accueil" tabindex="1">🏠</a> | |||
</p> | |||
</nav> | |||
<hr> | |||
<h2><a href="http://antirez.com/news/133">Source originale du contenu</a></h2> | |||
<p>When I started the Redis project more than ten years ago I was in one of the most exciting moments of my career. My co-founder and I had successfully launched two of the major web 2.0 services of the Italian web. In order to make them scalable we had to invent many new concepts, that were already known in the field most of the times, but we didn’t know, nor we cared to check. Problem? Let’s figure out a solution. We wanted to solve problems but we wanted, even more, to have fun. This was the playful environment where Redis was born.</p> | |||
<p>But now Redis is, incredibly, one of the main parts of so many things. And year after year my work changed from building this thing to making sure that it was also as useful as possible, as reliable as possible. And in recent years, what I do every day changed so much that most of my attention is spent in checking what other developers tell me about the Redis code, how to improve it, the changes it requires to be more correct or faster or more secure. However I never wanted to be a software maintainer.</p> | |||
<p>I write code in order to express myself, and I consider what I code an artifact, rather than just something useful to get things done. I would say that what I write is useful just as a side effect, but my first goal is to make something that is, in some way, beautiful. In essence, I would rather be remembered as a bad artist than a good programmer. Now I’m asked more and more, by the circumstances created by a project that became so important, to express myself less and to maintain the project more. And this is indeed exactly what Redis needs right now. But this is not what I want to do, and I stretched myself enough during the past years.</p> | |||
<p>So, dear Redis community, today I’m stepping back as the Redis maintainer. My new position will be, on one side, an “ideas” person at Redis Labs, in order to provide inputs for new Redis possibilities: I’ll continue to be part of the Redis Labs advisory board. On the other hand however my hands will be free, and I’ll do something else, that could be writing code or not, who knows, I don’t want to make plans for now. However I’m very skeptical about me not writing more code in the future. It’s just too much fun :D</p> | |||
<p>I leave Redis in the hands of the Redis community. I asked my colleagues Yossi Gottlieb and Oran Agra to continue to maintain the project starting from today: these are the people that helped me the most in recent years, and that tried hard, even when it was not “linear” to follow me in my very subjective point of views, to understand what my vision on Redis was. Since I don’t want to be part of how the new Redis development setup will be shaped (that is the most meta of the maintenance tasks, exactly what I want to avoid), I’ll just leave Yossi and Oran the task of understanding how to interface with the rest of the Redis developers to find a sustainable development model, you can hear directly from Yossi and Oran in this blog post: <a rel="nofollow" href="https://redislabs.com/blog/new-governance-for-redis/">https://redislabs.com/blog/new-governance-for-redis/</a></p> | |||
<p>I believe I’m not just leaving Redis in the hands of a community of expert programmers, but also in the hands of people who care about the legacy of the community spirit of Redis. In eleven years I hope I was able to provide a point of view that certain persons understood, about an alternative way to write software. I hope that such point of view will be taken into consideration in the evolution of Redis.</p> | |||
<p>Redis was the most stressful thing I did in my career, and probably also the most important. I don’t like much what the underground programming world became in recent years, but even if it was not an easy journey, I had the privilege to work and interact with many great individuals. Thank you for your humanity and your help, and for what you taught me. You know who you are! I want to also say thank you to the companies and individuals inside such companies that allowed me to write open source every day for so many years, with the freedom to do what I believed to be correct for the user base. Redis Labs, VMware and Pivotal, thank you for your great help and generosity.</p> | |||
<p>As I said, I don’t really know what there is for me in my future, other than the involvement with the Redis advisory board. I guess that for some time, just look around is a good idea, without doing too many things. I would like to explore more a few hobbies of mine. Writing blog posts is also a major thing that I wanted to do but did less and less because of time concerns. Recently I published videos in Italian language explaining technological concepts to the general public, I had fun doing that and received good feedbacks, maybe I’ll do more of that as well. Anyway I guess some of you know that I’m active on Twitter as @antirez. If you are interested in what an old, strange programmer will do next, see you there.</p> | |||
</article> | |||
<hr> | |||
<footer> | |||
<p> | |||
<a href="/david/" title="Aller à l’accueil">🏠</a> • | |||
<a href="/david/log/" title="Accès au flux RSS">🤖</a> • | |||
<a href="http://larlet.com" title="Go to my English profile" data-instant>🇨🇦</a> • | |||
<a href="mailto:david%40larlet.fr" title="Envoyer un courriel">📮</a> • | |||
<abbr title="Hébergeur : Alwaysdata, 62 rue Tiquetonne 75002 Paris, +33184162340">🧚</abbr> | |||
</p> | |||
<template id="theme-selector"> | |||
<form> | |||
<fieldset> | |||
<legend>Thème</legend> | |||
<label> | |||
<input type="radio" value="auto" name="chosen-color-scheme" checked> Auto | |||
</label> | |||
<label> | |||
<input type="radio" value="dark" name="chosen-color-scheme"> Foncé | |||
</label> | |||
<label> | |||
<input type="radio" value="light" name="chosen-color-scheme"> Clair | |||
</label> | |||
</fieldset> | |||
</form> | |||
</template> | |||
</footer> | |||
<script type="text/javascript"> | |||
function loadThemeForm(templateName) { | |||
const themeSelectorTemplate = document.querySelector(templateName) | |||
const form = themeSelectorTemplate.content.firstElementChild | |||
themeSelectorTemplate.replaceWith(form) | |||
form.addEventListener('change', (e) => { | |||
const chosenColorScheme = e.target.value | |||
localStorage.setItem('theme', chosenColorScheme) | |||
toggleTheme(chosenColorScheme) | |||
}) | |||
const selectedTheme = localStorage.getItem('theme') | |||
if (selectedTheme && selectedTheme !== 'undefined') { | |||
form.querySelector(`[value="${selectedTheme}"]`).checked = true | |||
} | |||
} | |||
const prefersColorSchemeDark = '(prefers-color-scheme: dark)' | |||
window.addEventListener('load', () => { | |||
let hasDarkRules = false | |||
for (const styleSheet of Array.from(document.styleSheets)) { | |||
let mediaRules = [] | |||
for (const cssRule of styleSheet.cssRules) { | |||
if (cssRule.type !== CSSRule.MEDIA_RULE) { | |||
continue | |||
} | |||
// WARNING: Safari does not have/supports `conditionText`. | |||
if (cssRule.conditionText) { | |||
if (cssRule.conditionText !== prefersColorSchemeDark) { | |||
continue | |||
} | |||
} else { | |||
if (cssRule.cssText.startsWith(prefersColorSchemeDark)) { | |||
continue | |||
} | |||
} | |||
mediaRules = mediaRules.concat(Array.from(cssRule.cssRules)) | |||
} | |||
// WARNING: do not try to insert a Rule to a styleSheet you are | |||
// currently iterating on, otherwise the browser will be stuck | |||
// in a infinite loop… | |||
for (const mediaRule of mediaRules) { | |||
styleSheet.insertRule(mediaRule.cssText) | |||
hasDarkRules = true | |||
} | |||
} | |||
if (hasDarkRules) { | |||
loadThemeForm('#theme-selector') | |||
} | |||
}) | |||
</script> | |||
</body> | |||
</html> |
@@ -0,0 +1,19 @@ | |||
title: The end of the Redis adventure | |||
url: http://antirez.com/news/133 | |||
hash_url: 5e366e8fe10507c713ca8d581daeb17c | |||
When I started the Redis project more than ten years ago I was in one of the most exciting moments of my career. My co-founder and I had successfully launched two of the major web 2.0 services of the Italian web. In order to make them scalable we had to invent many new concepts, that were already known in the field most of the times, but we didn’t know, nor we cared to check. Problem? Let’s figure out a solution. We wanted to solve problems but we wanted, even more, to have fun. This was the playful environment where Redis was born. | |||
But now Redis is, incredibly, one of the main parts of so many things. And year after year my work changed from building this thing to making sure that it was also as useful as possible, as reliable as possible. And in recent years, what I do every day changed so much that most of my attention is spent in checking what other developers tell me about the Redis code, how to improve it, the changes it requires to be more correct or faster or more secure. However I never wanted to be a software maintainer. | |||
I write code in order to express myself, and I consider what I code an artifact, rather than just something useful to get things done. I would say that what I write is useful just as a side effect, but my first goal is to make something that is, in some way, beautiful. In essence, I would rather be remembered as a bad artist than a good programmer. Now I’m asked more and more, by the circumstances created by a project that became so important, to express myself less and to maintain the project more. And this is indeed exactly what Redis needs right now. But this is not what I want to do, and I stretched myself enough during the past years. | |||
So, dear Redis community, today I’m stepping back as the Redis maintainer. My new position will be, on one side, an “ideas” person at Redis Labs, in order to provide inputs for new Redis possibilities: I’ll continue to be part of the Redis Labs advisory board. On the other hand however my hands will be free, and I’ll do something else, that could be writing code or not, who knows, I don’t want to make plans for now. However I’m very skeptical about me not writing more code in the future. It’s just too much fun :D | |||
I leave Redis in the hands of the Redis community. I asked my colleagues Yossi Gottlieb and Oran Agra to continue to maintain the project starting from today: these are the people that helped me the most in recent years, and that tried hard, even when it was not “linear” to follow me in my very subjective point of views, to understand what my vision on Redis was. Since I don’t want to be part of how the new Redis development setup will be shaped (that is the most meta of the maintenance tasks, exactly what I want to avoid), I’ll just leave Yossi and Oran the task of understanding how to interface with the rest of the Redis developers to find a sustainable development model, you can hear directly from Yossi and Oran in this blog post: <a rel="nofollow" href="https://redislabs.com/blog/new-governance-for-redis/">https://redislabs.com/blog/new-governance-for-redis/</a> | |||
I believe I’m not just leaving Redis in the hands of a community of expert programmers, but also in the hands of people who care about the legacy of the community spirit of Redis. In eleven years I hope I was able to provide a point of view that certain persons understood, about an alternative way to write software. I hope that such point of view will be taken into consideration in the evolution of Redis. | |||
Redis was the most stressful thing I did in my career, and probably also the most important. I don’t like much what the underground programming world became in recent years, but even if it was not an easy journey, I had the privilege to work and interact with many great individuals. Thank you for your humanity and your help, and for what you taught me. You know who you are! I want to also say thank you to the companies and individuals inside such companies that allowed me to write open source every day for so many years, with the freedom to do what I believed to be correct for the user base. Redis Labs, VMware and Pivotal, thank you for your great help and generosity. | |||
As I said, I don’t really know what there is for me in my future, other than the involvement with the Redis advisory board. I guess that for some time, just look around is a good idea, without doing too many things. I would like to explore more a few hobbies of mine. Writing blog posts is also a major thing that I wanted to do but did less and less because of time concerns. Recently I published videos in Italian language explaining technological concepts to the general public, I had fun doing that and received good feedbacks, maybe I’ll do more of that as well. Anyway I guess some of you know that I’m active on Twitter as @antirez. If you are interested in what an old, strange programmer will do next, see you there. |
@@ -0,0 +1,187 @@ | |||
<!doctype html><!-- This is a valid HTML5 document. --> | |||
<!-- Screen readers, SEO, extensions and so on. --> | |||
<html lang="fr"> | |||
<!-- Has to be within the first 1024 bytes, hence before the <title> | |||
See: https://www.w3.org/TR/2012/CR-html5-20121217/document-metadata.html#charset --> | |||
<meta charset="utf-8"> | |||
<!-- Why no `X-UA-Compatible` meta: https://stackoverflow.com/a/6771584 --> | |||
<!-- The viewport meta is quite crowded and we are responsible for that. | |||
See: https://codepen.io/tigt/post/meta-viewport-for-2015 --> | |||
<meta name="viewport" content="width=device-width,initial-scale=1"> | |||
<!-- Required to make a valid HTML5 document. --> | |||
<title>lion affranchi (archive) — David Larlet</title> | |||
<!-- That good ol' feed, subscribe :). --> | |||
<link rel="alternate" type="application/atom+xml" title="Feed" href="/david/log/"> | |||
<!-- Generated from https://realfavicongenerator.net/ such a mess. --> | |||
<link rel="apple-touch-icon" sizes="180x180" href="/static/david/icons2/apple-touch-icon.png"> | |||
<link rel="icon" type="image/png" sizes="32x32" href="/static/david/icons2/favicon-32x32.png"> | |||
<link rel="icon" type="image/png" sizes="16x16" href="/static/david/icons2/favicon-16x16.png"> | |||
<link rel="manifest" href="/static/david/icons2/site.webmanifest"> | |||
<link rel="mask-icon" href="/static/david/icons2/safari-pinned-tab.svg" color="#07486c"> | |||
<link rel="shortcut icon" href="/static/david/icons2/favicon.ico"> | |||
<meta name="msapplication-TileColor" content="#f0f0ea"> | |||
<meta name="msapplication-config" content="/static/david/icons2/browserconfig.xml"> | |||
<meta name="theme-color" content="#f0f0ea"> | |||
<!-- Documented, feel free to shoot an email. --> | |||
<link rel="stylesheet" href="/static/david/css/style_2020-06-19.css"> | |||
<!-- See https://www.zachleat.com/web/comprehensive-webfonts/ for the trade-off. --> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_regular.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_bold.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_italic.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_regular.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_bold.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_italic.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin> | |||
<script type="text/javascript"> | |||
function toggleTheme(themeName) { | |||
document.documentElement.classList.toggle( | |||
'forced-dark', | |||
themeName === 'dark' | |||
) | |||
document.documentElement.classList.toggle( | |||
'forced-light', | |||
themeName === 'light' | |||
) | |||
} | |||
const selectedTheme = localStorage.getItem('theme') | |||
if (selectedTheme !== 'undefined') { | |||
toggleTheme(selectedTheme) | |||
} | |||
</script> | |||
<meta name="robots" content="noindex, nofollow"> | |||
<meta content="origin-when-cross-origin" name="referrer"> | |||
<!-- Canonical URL for SEO purposes --> | |||
<link rel="canonical" href="https://www.la-grange.net/2020/07/01/affranchi"> | |||
<body class="remarkdown h1-underline h2-underline h3-underline hr-center ul-star pre-tick"> | |||
<article> | |||
<h1>lion affranchi</h1> | |||
<nav> | |||
<p class="center"> | |||
<a href="/david/" title="Aller à l’accueil" tabindex="1">🏠</a> | |||
</p> | |||
</nav> | |||
<hr> | |||
<h2><a href="https://www.la-grange.net/2020/07/01/affranchi">Source originale du contenu</a></h2> | |||
<figure> | |||
<img src="https://www.la-grange.net/2020/07/01/8269-tampon-lion.jpg" alt="Lion en marbre"/> | |||
<figcaption>Tsujido, Japon, 1er juillet 2020</figcaption> | |||
</figure> | |||
<blockquote> | |||
<p>Good times are going to come our way too, she'd say. We just have to keep doing out best and work hard.— That's the way she was always thinking. I guess that's why she kept working with a vengeance.<br/> | |||
— Comrade Taguchi's Sorrow (An anthology of Japanese Proletarian Literature) - Kobayashi Takiji, urn:isbn:978-0-226-06837-4</p> | |||
</blockquote> | |||
<p>Dans la maison d'une artiste, laissée à l'abandon, qu'un ami a racheté, tout était en place, juste avec un peu plus de poussières. J'ai récupéré des objets ici et là, dont deux petits lions en marbre qui sont des sceaux encreurs au nom de l'artiste.</p> | |||
<p>Je les regarde souvent. Ils me rappellent le moment de la découverte de la maison, la poésie de son oubli. Je me demande aussi souvent si je devais réaliser un <a href="https://www.la-grange.net/2020/06/03/sceau">sceau</a> similaire, quel serait le motif sculpté sur le dessus ? Un chêne ? Une représentation de La Grange ? Et quels caractères pour le sceau, mon nom en japonais comme le sceau actuel, ou le mot Grange (納屋). Et pourquoi y mettre un nom ? L'objet doit il être uniquement fonctionnel ou avoir le caractère d'une émotion.</p> | |||
<h2>sur le bord du chemin</h2> | |||
<ul> | |||
<li><p><a href="https://argdown.org/">argdown</a>. Une syntaxe texte pour décrire et gérer un débat à propos d'un sujet. Il est possible de voir une représentation graphique du débat. Voir <a href="https://argdown.org/sandbox/html">cet example</a>.</p> | |||
</li> | |||
<li><p>20% du <a href="https://seabed2030.gebco.net/news/gebco_2020_release.html">fond des océans est maintenant cartographié</a>. En 2017 uniquement 6% était cartographié.</p> | |||
<blockquote> | |||
<p>The sustained increase in data available to map the ocean floor will enable Seabed 2030 to play a leading role in delivering a comprehensive set of <strong>authoritative data that is freely available for all to use</strong>.</p> | |||
</blockquote> | |||
<p><a href="https://www.gebco.net/data_and_products/">data set and products</a>. Il existe aussi un <a href="https://www.ngdc.noaa.gov/gazetteer/">outil de navigation de la carte</a>.</p> | |||
<p><img src="https://www.la-grange.net/2020/07/01/ocean-japon.jpg" alt="" fond="" de="" l="" pr="" du="" japon=""/></p> | |||
<p>Peut-être un jour donnerons-nous des noms encore plus localisés ? Il existe des « rivières » au fond de l'océan. Près de Tokyo, le <a href="https://www.sciencedirect.com/science/article/abs/pii/002532279090038L">Canyon de Boso</a> semble se jeter dans le bassin de Katsuura.</p> | |||
<p><img src="https://www.la-grange.net/2020/07/01/boso-canyon.jpg" alt="" carte="" du="" canyon="" boso=""/></p> | |||
</li> | |||
<li><p><a href="http://antirez.com/news/133">The end of the Redis adventure</a>.</p> | |||
<blockquote> | |||
<p>I write code in order to express myself, and I consider what I code an artifact, rather than just something useful to get things done. I would say that what I write is useful just as a side effect, but my first goal is to make something that is, in some way, beautiful. <strong>In essence, I would rather be remembered as a bad artist than a good programmer</strong>.</p> | |||
</blockquote> | |||
</li> | |||
<li><p>Sur la boîte aux lettres, cherchant un abri pour éviter la pluie, un <a href="https://en.wikipedia.org/wiki/Acalolepta_fraudatrix">Acalolepta fraudatrix</a>. Il a de très <a href="http://www.forest.kyushu-u.ac.jp/photo/hokkaido/db-image/image00447.jpg">longues antennes</a> et a un corps long de près de 3 cm. J'ai oublié de prendre une photo. Dommage.</p> | |||
</li> | |||
</ul> | |||
</article> | |||
<hr> | |||
<footer> | |||
<p> | |||
<a href="/david/" title="Aller à l’accueil">🏠</a> • | |||
<a href="/david/log/" title="Accès au flux RSS">🤖</a> • | |||
<a href="http://larlet.com" title="Go to my English profile" data-instant>🇨🇦</a> • | |||
<a href="mailto:david%40larlet.fr" title="Envoyer un courriel">📮</a> • | |||
<abbr title="Hébergeur : Alwaysdata, 62 rue Tiquetonne 75002 Paris, +33184162340">🧚</abbr> | |||
</p> | |||
<template id="theme-selector"> | |||
<form> | |||
<fieldset> | |||
<legend>Thème</legend> | |||
<label> | |||
<input type="radio" value="auto" name="chosen-color-scheme" checked> Auto | |||
</label> | |||
<label> | |||
<input type="radio" value="dark" name="chosen-color-scheme"> Foncé | |||
</label> | |||
<label> | |||
<input type="radio" value="light" name="chosen-color-scheme"> Clair | |||
</label> | |||
</fieldset> | |||
</form> | |||
</template> | |||
</footer> | |||
<script type="text/javascript"> | |||
function loadThemeForm(templateName) { | |||
const themeSelectorTemplate = document.querySelector(templateName) | |||
const form = themeSelectorTemplate.content.firstElementChild | |||
themeSelectorTemplate.replaceWith(form) | |||
form.addEventListener('change', (e) => { | |||
const chosenColorScheme = e.target.value | |||
localStorage.setItem('theme', chosenColorScheme) | |||
toggleTheme(chosenColorScheme) | |||
}) | |||
const selectedTheme = localStorage.getItem('theme') | |||
if (selectedTheme && selectedTheme !== 'undefined') { | |||
form.querySelector(`[value="${selectedTheme}"]`).checked = true | |||
} | |||
} | |||
const prefersColorSchemeDark = '(prefers-color-scheme: dark)' | |||
window.addEventListener('load', () => { | |||
let hasDarkRules = false | |||
for (const styleSheet of Array.from(document.styleSheets)) { | |||
let mediaRules = [] | |||
for (const cssRule of styleSheet.cssRules) { | |||
if (cssRule.type !== CSSRule.MEDIA_RULE) { | |||
continue | |||
} | |||
// WARNING: Safari does not have/supports `conditionText`. | |||
if (cssRule.conditionText) { | |||
if (cssRule.conditionText !== prefersColorSchemeDark) { | |||
continue | |||
} | |||
} else { | |||
if (cssRule.cssText.startsWith(prefersColorSchemeDark)) { | |||
continue | |||
} | |||
} | |||
mediaRules = mediaRules.concat(Array.from(cssRule.cssRules)) | |||
} | |||
// WARNING: do not try to insert a Rule to a styleSheet you are | |||
// currently iterating on, otherwise the browser will be stuck | |||
// in a infinite loop… | |||
for (const mediaRule of mediaRules) { | |||
styleSheet.insertRule(mediaRule.cssText) | |||
hasDarkRules = true | |||
} | |||
} | |||
if (hasDarkRules) { | |||
loadThemeForm('#theme-selector') | |||
} | |||
}) | |||
</script> | |||
</body> | |||
</html> |
@@ -0,0 +1,35 @@ | |||
title: lion affranchi | |||
url: https://www.la-grange.net/2020/07/01/affranchi | |||
hash_url: 613da2c8a82cb70c50391a34565800c4 | |||
<figure> | |||
<img src="https://www.la-grange.net/2020/07/01/8269-tampon-lion.jpg" alt="Lion en marbre"/> | |||
<figcaption>Tsujido, Japon, 1er juillet 2020</figcaption> | |||
</figure> | |||
<blockquote> | |||
<p>Good times are going to come our way too, she'd say. We just have to keep doing out best and work hard.— That's the way she was always thinking. I guess that's why she kept working with a vengeance.<br/> | |||
— Comrade Taguchi's Sorrow (An anthology of Japanese Proletarian Literature) - Kobayashi Takiji, urn:isbn:978-0-226-06837-4</p> | |||
</blockquote> | |||
<p>Dans la maison d'une artiste, laissée à l'abandon, qu'un ami a racheté, tout était en place, juste avec un peu plus de poussières. J'ai récupéré des objets ici et là, dont deux petits lions en marbre qui sont des sceaux encreurs au nom de l'artiste.</p> | |||
<p>Je les regarde souvent. Ils me rappellent le moment de la découverte de la maison, la poésie de son oubli. Je me demande aussi souvent si je devais réaliser un <a href="https://www.la-grange.net/2020/06/03/sceau">sceau</a> similaire, quel serait le motif sculpté sur le dessus ? Un chêne ? Une représentation de La Grange ? Et quels caractères pour le sceau, mon nom en japonais comme le sceau actuel, ou le mot Grange (納屋). Et pourquoi y mettre un nom ? L'objet doit il être uniquement fonctionnel ou avoir le caractère d'une émotion.</p> | |||
<h2>sur le bord du chemin</h2> | |||
<ul> | |||
<li><p><a href="https://argdown.org/">argdown</a>. Une syntaxe texte pour décrire et gérer un débat à propos d'un sujet. Il est possible de voir une représentation graphique du débat. Voir <a href="https://argdown.org/sandbox/html">cet example</a>.</p> | |||
</li> | |||
<li><p>20% du <a href="https://seabed2030.gebco.net/news/gebco_2020_release.html">fond des océans est maintenant cartographié</a>. En 2017 uniquement 6% était cartographié.</p> | |||
<blockquote> | |||
<p>The sustained increase in data available to map the ocean floor will enable Seabed 2030 to play a leading role in delivering a comprehensive set of <strong>authoritative data that is freely available for all to use</strong>.</p> | |||
</blockquote> | |||
<p><a href="https://www.gebco.net/data_and_products/">data set and products</a>. Il existe aussi un <a href="https://www.ngdc.noaa.gov/gazetteer/">outil de navigation de la carte</a>.</p> | |||
<p><img src="https://www.la-grange.net/2020/07/01/ocean-japon.jpg" alt="" fond="" de="" l="" pr="" du="" japon=""/></p> | |||
<p>Peut-être un jour donnerons-nous des noms encore plus localisés ? Il existe des « rivières » au fond de l'océan. Près de Tokyo, le <a href="https://www.sciencedirect.com/science/article/abs/pii/002532279090038L">Canyon de Boso</a> semble se jeter dans le bassin de Katsuura.</p> | |||
<p><img src="https://www.la-grange.net/2020/07/01/boso-canyon.jpg" alt="" carte="" du="" canyon="" boso=""/></p> | |||
</li> | |||
<li><p><a href="http://antirez.com/news/133">The end of the Redis adventure</a>.</p> | |||
<blockquote> | |||
<p>I write code in order to express myself, and I consider what I code an artifact, rather than just something useful to get things done. I would say that what I write is useful just as a side effect, but my first goal is to make something that is, in some way, beautiful. <strong>In essence, I would rather be remembered as a bad artist than a good programmer</strong>.</p> | |||
</blockquote> | |||
</li> | |||
<li><p>Sur la boîte aux lettres, cherchant un abri pour éviter la pluie, un <a href="https://en.wikipedia.org/wiki/Acalolepta_fraudatrix">Acalolepta fraudatrix</a>. Il a de très <a href="http://www.forest.kyushu-u.ac.jp/photo/hokkaido/db-image/image00447.jpg">longues antennes</a> et a un corps long de près de 3 cm. J'ai oublié de prendre une photo. Dommage.</p> | |||
</li> | |||
</ul> |
@@ -0,0 +1,181 @@ | |||
<!doctype html><!-- This is a valid HTML5 document. --> | |||
<!-- Screen readers, SEO, extensions and so on. --> | |||
<html lang="fr"> | |||
<!-- Has to be within the first 1024 bytes, hence before the <title> | |||
See: https://www.w3.org/TR/2012/CR-html5-20121217/document-metadata.html#charset --> | |||
<meta charset="utf-8"> | |||
<!-- Why no `X-UA-Compatible` meta: https://stackoverflow.com/a/6771584 --> | |||
<!-- The viewport meta is quite crowded and we are responsible for that. | |||
See: https://codepen.io/tigt/post/meta-viewport-for-2015 --> | |||
<meta name="viewport" content="width=device-width,initial-scale=1"> | |||
<!-- Required to make a valid HTML5 document. --> | |||
<title>Isabelle Attard : « L’écologie doit s’inscrire au sein du mouvement révolutionnaire » (archive) — David Larlet</title> | |||
<!-- That good ol' feed, subscribe :). --> | |||
<link rel="alternate" type="application/atom+xml" title="Feed" href="/david/log/"> | |||
<!-- Generated from https://realfavicongenerator.net/ such a mess. --> | |||
<link rel="apple-touch-icon" sizes="180x180" href="/static/david/icons2/apple-touch-icon.png"> | |||
<link rel="icon" type="image/png" sizes="32x32" href="/static/david/icons2/favicon-32x32.png"> | |||
<link rel="icon" type="image/png" sizes="16x16" href="/static/david/icons2/favicon-16x16.png"> | |||
<link rel="manifest" href="/static/david/icons2/site.webmanifest"> | |||
<link rel="mask-icon" href="/static/david/icons2/safari-pinned-tab.svg" color="#07486c"> | |||
<link rel="shortcut icon" href="/static/david/icons2/favicon.ico"> | |||
<meta name="msapplication-TileColor" content="#f0f0ea"> | |||
<meta name="msapplication-config" content="/static/david/icons2/browserconfig.xml"> | |||
<meta name="theme-color" content="#f0f0ea"> | |||
<!-- Documented, feel free to shoot an email. --> | |||
<link rel="stylesheet" href="/static/david/css/style_2020-06-19.css"> | |||
<!-- See https://www.zachleat.com/web/comprehensive-webfonts/ for the trade-off. --> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_regular.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_bold.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_italic.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_regular.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_bold.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin> | |||
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_italic.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin> | |||
<script type="text/javascript"> | |||
function toggleTheme(themeName) { | |||
document.documentElement.classList.toggle( | |||
'forced-dark', | |||
themeName === 'dark' | |||
) | |||
document.documentElement.classList.toggle( | |||
'forced-light', | |||
themeName === 'light' | |||
) | |||
} | |||
const selectedTheme = localStorage.getItem('theme') | |||
if (selectedTheme !== 'undefined') { | |||
toggleTheme(selectedTheme) | |||
} | |||
</script> | |||
<meta name="robots" content="noindex, nofollow"> | |||
<meta content="origin-when-cross-origin" name="referrer"> | |||
<!-- Canonical URL for SEO purposes --> | |||
<link rel="canonical" href="https://www.revue-ballast.fr/isabelle-attard-lecologie-doit-sinscrire-au-sein-du-mouvement-revolutionnaire"> | |||
<body class="remarkdown h1-underline h2-underline h3-underline hr-center ul-star pre-tick"> | |||
<article> | |||
<h1>Isabelle Attard : « L’écologie doit s’inscrire au sein du mouvement révolutionnaire »</h1> | |||
<nav> | |||
<p class="center"> | |||
<a href="/david/" title="Aller à l’accueil" tabindex="1">🏠</a> | |||
</p> | |||
</nav> | |||
<hr> | |||
<h2><a href="https://www.revue-ballast.fr/isabelle-attard-lecologie-doit-sinscrire-au-sein-du-mouvement-revolutionnaire">Source originale du contenu</a></h2> | |||
<p><span><em>Le temps d’un mandat, Isabelle Attard, archéozoologue de formation, a défendu à l’Assemblée nationale les couleurs d’Europe Écologie – les Verts. Sous les ors du palais Bourbon, elle est l’une des rares députés à s’opposer, en 2015, à la prolongation de l’état d’urgence et, la même année, à celle des frappes aériennes sur le sol syrien. Deux ans après la fin de sa députation, elle publie le livre </em>Comment je suis devenue anarchiste : <em>un ralliement explicite à la tradition libertaire, doublé d’un constat sans appel quant à la possibilité de changer le système de l’intérieur. Certaine que la lutte écologique, féministe et anticapitaliste ne passera plus par la prise du pouvoir central, elle aspire à la création, ici et maintenant, d’espaces parallèles autonomes. Nous en discutons ensemble.<br/> </em></span></p> | |||
<p><hr/> | |||
<p><span><strong><picture class="wp-image-73706 size-full alignleft"> | |||
<source type="image/webp" data-lazy-srcset="https://www.revue-ballast.fr/wp-content/uploads/2020/06/attard-isabelle.jpg.webp 300w" srcset="data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20300%20300'%3E%3C/svg%3E" data-lazy-sizes="(max-width: 300px) 100vw, 300px"/> | |||
<img src="" data-lazy-srcset="https://www.revue-ballast.fr/wp-content/uploads/2020/06/attard-isabelle.jpg 300w, https://www.revue-ballast.fr/wp-content/uploads/2020/06/attard-isabelle-150x150.jpg 150w, https://www.revue-ballast.fr/wp-content/uploads/2020/06/attard-isabelle-100x100.jpg 100w" data-lazy-sizes="(max-width: 300px) 100vw, 300px" data-lazy-src="https://www.revue-ballast.fr/wp-content/uploads/2020/06/attard-isabelle.jpg"/> | |||
</picture> | |||
<noscript><picture class="wp-image-73706 size-full alignleft"> | |||
<source type="image/webp" srcset="https://www.revue-ballast.fr/wp-content/uploads/2020/06/attard-isabelle.jpg.webp 300w" sizes="(max-width: 300px) 100vw, 300px"/> | |||
<img src="https://www.revue-ballast.fr/wp-content/uploads/2020/06/attard-isabelle.jpg" srcset="https://www.revue-ballast.fr/wp-content/uploads/2020/06/attard-isabelle.jpg 300w, https://www.revue-ballast.fr/wp-content/uploads/2020/06/attard-isabelle-150x150.jpg 150w, https://www.revue-ballast.fr/wp-content/uploads/2020/06/attard-isabelle-100x100.jpg 100w" sizes="(max-width: 300px) 100vw, 300px"/> | |||
</picture> | |||
</noscript>Vous avez été députée cinq ans. Votre constat est sans appel : on ne peut rien faire bouger au sein des institutions. À vos yeux, l’opposition parlementaire est-elle candide, tristement lucide ou vraiment complice ?</strong></span></p><p>Effectivement. Et je peux même dire que je n’étais pas vraiment prévue au programme puisque la circonscription dans laquelle je me suis présentée ne m’était pas du tout favorable. Je débutais en politique et très peu de personnes croyaient en une victoire possible. Je ne la dois finalement qu’à la grande division qui régnait alors à droite comme à gauche. Lorsque je suis entrée à l’Assemblée nationale, je ne faisais pas partie du sérail, j’ai donc découvert son fonctionnement, ainsi que les combinaisons politiques, en me jetant directement dans le grand bain. Comme n’importe quelle personne qui croit encore à ce système, j’étais pétrie de grands principes républicains et d’idéaux démocratiques. J’ai assez vite déchanté. Lorsque je n’ai pas voté le budget en 2013, je me suis de facto retrouvée dans la position d’une opposante à la majorité présidentielle. Dès lors, celle-ci n’a eu de cesse de me marginaliser. La plupart du temps, elle préférait d’ailleurs m’ignorer — il serait même encore plus juste de dire qu’elle me dédaignait. Il n’existe que deux camps à l’Assemblée : soit vous soutenez la majorité, soit vous vous y opposez. C’est très manichéen. Or si j’étais franchement en désaccord avec la politique du gouvernement, je n’avais rien à voir avec l’<span class="caps">UMP</span> ou le <span class="caps">FN</span>. J’ai bien essayé, avec d’autres collègues, déçus comme moi, de proposer en 2015 la création d’un groupe « rouge-rose-vert » qui aurait alors permis d’apporter une autre voix, mais nous n’avons reçu que très peu d’écho.</p> | |||
<p><span><strong>Comment l’expliquez-vous ?</strong></span></p><blockquote><p>« L’Assemblée nationale est un grand théâtre dans lequel la pièce est déjà écrite à l’avance. Chacun y tient le rôle qui lui a été attribué. »</p></blockquote><p>Ça ne correspondait pas à la stratégie des écuries présidentielles de l’ |