From aa6cd8916735cbdcb495608d00b0d5b01010759f Mon Sep 17 00:00:00 2001 From: Nishant Arora <1895906+whizzzkid@users.noreply.github.com> Date: Wed, 14 Dec 2022 11:13:40 -0700 Subject: [PATCH] docs: add release process and move to ./docs (#1113) Co-authored-by: Marcin Rataj --- README.md | 20 +++-- CONTRIBUTING.md => docs/CONTRIBUTING.md | 8 +- DEVELOPER-NOTES.md => docs/DEVELOPER-NOTES.md | 42 ++++++----- .../LOCALIZATION-NOTES.md | 10 ++- docs/RELEASE-PROCESS.md | 75 +++++++++++++++++++ 5 files changed, 120 insertions(+), 35 deletions(-) rename CONTRIBUTING.md => docs/CONTRIBUTING.md (83%) rename DEVELOPER-NOTES.md => docs/DEVELOPER-NOTES.md (86%) rename LOCALIZATION-NOTES.md => docs/LOCALIZATION-NOTES.md (85%) create mode 100644 docs/RELEASE-PROCESS.md diff --git a/README.md b/README.md index afe90c7fc..183bd49c2 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![](https://img.shields.io/github/release/ipfs/ipfs-companion.svg)](https://github.com/ipfs/ipfs-companion/releases/latest) [![](https://img.shields.io/badge/mozilla-reviewed-blue.svg)](https://addons.mozilla.org/en-US/firefox/addon/ipfs-companion/) -[![i18n status](https://img.shields.io/badge/i18n-translated-blue.svg)](https://github.com/ipfs-shipyard/ipfs-companion/blob/main/LOCALIZATION-NOTES.md) +[![i18n status](https://img.shields.io/badge/i18n-translated-blue.svg)](https://github.com/ipfs-shipyard/ipfs-companion/blob/main/docs/LOCALIZATION-NOTES.md) [![](https://img.shields.io/badge/matrix%20chat-%23lobby:ipfs.io-blue.svg?style=flat-square)](https://matrix.to/#/#lobby:ipfs.io) ![Quick runthrough of basic IPFS Companion features](https://gateway.ipfs.io/ipfs/QmSsGphTN1eWMhkFFNFb23jWTXyhNbo47PF9FbmC6ZaRNg) @@ -40,7 +40,7 @@ IPFS is a peer-to-peer hypermedia protocol designed to make the web faster, safe #### Detect URLs with IPFS paths IPFS Companion detects and tests requests for IPFS-like paths ( such as `/ipfs/{cid}` or `/ipns/{peerid_or_host-with-dnslink}`) on any website. If a path is a [valid IPFS address](https://github.com/ipfs/is-ipfs), it is redirected to load from your local gateway. The gateway at `localhost` will also automatically switch to a subdomain to provide a unique origin for each website: -> `https://ipfs.io/ipfs/QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR` +> `https://ipfs.io/ipfs/QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR` > → `http://localhost:8080/ipfs/QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR` > → `http://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi.ipfs.localhost:8080` @@ -48,8 +48,8 @@ IPFS Companion detects and tests requests for IPFS-like paths ( such as `/ipfs/{ IPFS Companion [detects DNSLink info](http://docs.ipfs.io/how-to/dnslink-companion/) in the DNS records of websites. If a site uses DNSLink (a few examples are https://docs.ipfs.io, https://ipld.io, and http://tr.wikipedia-on-ipfs.org), IPFS Companion redirects the HTTP request to your local gateway: -> `http://docs.ipfs.io` -> → `http://localhost:8080/ipns/docs.ipfs.io` → `http://docs.ipfs.io.ipns.localhost:8080/` +> `http://docs.ipfs.tech` +> → `http://localhost:8080/ipns/docs.ipfs.tech` → `http://docs.ipfs.tech.ipns.localhost:8080/` #### Detect pages with `x-ipfs-path` headers @@ -126,7 +126,7 @@ but these builds are not signed, nor will automatically update. `.zip` bundles a ### Development -To work on IPFS Companion's code, you'll need to install it from source. Quick steps are below, but see the full [developer notes](DEVELOPER-NOTES.md) for more detailed instructions and tips. +To work on IPFS Companion's code, you'll need to install it from source. Quick steps are below, but see the full [developer notes](./docs/DEVELOPER-NOTES.md) for more detailed instructions and tips. 1. Clone https://github.com/ipfs-shipyard/ipfs-companion.git 2. Run this all-in-one dev build to install dependencies, build, and launch in the browser of your choice: @@ -141,13 +141,17 @@ To work on IPFS Companion's code, you'll need to install it from source. Quick s ## Contribute -[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](CONTRIBUTING.md) +[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](./docs/CONTRIBUTING.md) All are welcome to help make IPFS Companion even better! -- Check out the [contribution guide](CONTRIBUTING.md) for how to get started as a developer +- Check out the [contribution guide](./docs/CONTRIBUTING.md) for how to get started as a developer - Open an [issue](https://github.com/ipfs/ipfs-companion/issues) - Make sure you read and abide by the [IPFS Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md) +## Release Process + +The release process has been [documented here](./docs/RELEASE-PROCESS.md). + ## Help & troubleshooting ### Ask a question @@ -171,7 +175,7 @@ Deny ## Privacy & license info -- IPFS Companion [Privacy policy](PRIVACY-POLICY.md) +- IPFS Companion [Privacy policy](./PRIVACY-POLICY.md) - The IPFS logo belongs to the [IPFS Project](https://github.com/ipfs) and is licensed under a CC-BY-SA 3.0 license - [is-ipfs](https://github.com/ipfs-shipyard/is-ipfs), [js-multihash](https://github.com/multiformats/js-multihash), and other npm dependencies are under MIT license, unless stated otherwise - IPFS Companion itself is released under [CC0](LICENSE); to the extent possible under law, the author has waived all copyright and related or neighboring rights to this work, effectively placing it in the public domain diff --git a/CONTRIBUTING.md b/docs/CONTRIBUTING.md similarity index 83% rename from CONTRIBUTING.md rename to docs/CONTRIBUTING.md index 537c6fd3b..c14520cbc 100644 --- a/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -14,7 +14,7 @@ Do not hesitate and [create a new Issue](https://github.com/ipfs/ipfs-companion/ ### Working on existing Issues -Feel free to work on issues that are [not assigned yet](https://github.com/ipfs/ipfs-companion/issues?utf8=✓&q=is%3Aissue+is%3Aopen+no%3Aassignee), especially ones marked with [help wanted](https://github.com/ipfs/ipfs-companion/issues?q=is%3Aopen+label%3A%22help+wanted%22+no%3Aassignee) tag. +Feel free to work on issues that are [not assigned yet](https://github.com/ipfs/ipfs-companion/issues?utf8=✓&q=is%3Aissue+is%3Aopen+no%3Aassignee), especially ones marked with [help wanted](https://github.com/ipfs/ipfs-companion/issues?q=is%3Aopen+label%3A%22help+wanted%22+no%3Aassignee) tag. As a courtesy, please add a comment informing about your intent. That way we will not duplicate effort. ### Submitting Pull Requests @@ -28,14 +28,14 @@ See the [GitHub Flow Guide](https://guides.github.com/introduction/flow/) for de Go to Transifex and join [IPFS Companion Translation Project](https://www.transifex.com/ipfs/ipfs-companion/) :sparkles: -If you want to download translations from Transifex and run them locally, make sure to read [Localization Notes](LOCALIZATION-NOTES.md) first. +If you want to download translations from Transifex and run them locally, make sure to read [Localization Notes](./LOCALIZATION-NOTES.md) first. ## Writing Code -**If you plan to write code make sure to read [Developer Notes](DEVELOPER-NOTES.md) to get familiar with tools and commands that will make your work easier.** +**If you plan to write code make sure to read [Developer Notes](./docs/DEVELOPER-NOTES.md) to get familiar with tools and commands that will make your work easier.** ## How to Help with Things Beyond Browser Extension? - https://github.com/ipfs/in-web-browsers -- https://github.com/ipfs/community/blob/master/CONTRIBUTING.md +- https://github.com/ipfs/community/blob/master/CONTRIBUTING.md [![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) diff --git a/DEVELOPER-NOTES.md b/docs/DEVELOPER-NOTES.md similarity index 86% rename from DEVELOPER-NOTES.md rename to docs/DEVELOPER-NOTES.md index ec01810e7..9519c5ccf 100644 --- a/DEVELOPER-NOTES.md +++ b/docs/DEVELOPER-NOTES.md @@ -2,21 +2,23 @@ ### Table of contents -* [Build from source](#build-from-source) - * [Clone and install dependencies](#clone-and-install-dependencies) - * [Build and run in Firefox](#build-and-run-in-firefox) - * [Build and run in Chromium](#build-and-run-in-chromium) - * [Run build on file changes](#run-build-on-file-changes) -* [Reproducible build in Docker](#reproducible-build-in-docker) -* [Useful tasks](#useful-tasks) -* [Other tips](#other-tips) -* [Legacy Firefox (< 53) and XUL-compatible browsers](#legacy-firefox--53-and-xul-compatible-browsers) -* [Using IPFS Companion on Firefox for Android](#using-ipfs-companion-on-firefox-for-android) - * [Install Firefox for Android](#install-firefox-for-android) - * [Install IPFS Companion](#install-ipfs-companion) - * [Hot-deploy over USB](#hot-deploy-over-usb) - * [Debugging in Firefox for Android](#debugging-in-firefox-for-android) - * [Further resources](#further-resources) +- [Developer notes for IPFS Companion](#developer-notes-for-ipfs-companion) + - [Table of contents](#table-of-contents) + - [Build from source](#build-from-source) + - [Clone and install dependencies](#clone-and-install-dependencies) + - [Build and run in Firefox](#build-and-run-in-firefox) + - [Build and run in Chromium](#build-and-run-in-chromium) + - [Run build on file changes](#run-build-on-file-changes) + - [Reproducible build in Docker](#reproducible-build-in-docker) + - [Useful tasks](#useful-tasks) + - [Other tips](#other-tips) + - [Legacy Firefox (\< 53) and XUL-compatible browsers](#legacy-firefox--53-and-xul-compatible-browsers) + - [Using IPFS Companion on Firefox for Android](#using-ipfs-companion-on-firefox-for-android) + - [Install Firefox for Android](#install-firefox-for-android) + - [Install IPFS Companion](#install-ipfs-companion) + - [Hot-deploy over USB](#hot-deploy-over-usb) + - [Debugging in Firefox for Android](#debugging-in-firefox-for-android) + - [Further resources](#further-resources) ## Build from source @@ -52,7 +54,7 @@ npm run test # test suite npm run firefox # spawn new Firefox ``` -It is also possible to load the extension manually: +It is also possible to load the extension manually: 1. Enter `about:debugging` in the address bar 2. Click "This Firefox" in the left nav 3. Click "Load Temporary Add-on..." @@ -92,8 +94,8 @@ npm run watch # watch for new changes ## Reproducible build in Docker -Want to ensure prebuilt bundle does not include any additional code? -Don't want to install JS dependencies such as NodeJS and yarn? +Want to ensure prebuilt bundle does not include any additional code? +Don't want to install JS dependencies such as NodeJS and yarn? Do an isolated build inside of Docker! @@ -143,12 +145,12 @@ Release build shortcuts: export PATH="/path/to/alternative/version/of/firefox/:${PATH}" ``` -- [Using localization in IPFS Companion](LOCALIZATION-NOTES.md) (running browsers with specific locale, etc) +- [Using localization in IPFS Companion](./LOCALIZATION-NOTES.md) (running browsers with specific locale, etc) - [Testing persistent and restart features (Mozilla)](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Testing_persistent_and_restart_features) ## Legacy Firefox (< 53) and XUL-compatible browsers -Legacy versions `1.x.x` were based on currently deprecated Add-On SDK (Firefox-only). +Legacy versions `1.x.x` were based on currently deprecated Add-On SDK (Firefox-only). While it is not maintained any more, one can inspect, build, and install it using codebase from [legacy-sdk](https://github.com/ipfs/ipfs-companion/tree/legacy-sdk) branch. For historical background on the rewrite, see [Issue #20: Move to WebExtensions](https://github.com/ipfs/ipfs-companion/issues/20). ## Using IPFS Companion on Firefox for Android diff --git a/LOCALIZATION-NOTES.md b/docs/LOCALIZATION-NOTES.md similarity index 85% rename from LOCALIZATION-NOTES.md rename to docs/LOCALIZATION-NOTES.md index bee5897e4..1a957a1a6 100644 --- a/LOCALIZATION-NOTES.md +++ b/docs/LOCALIZATION-NOTES.md @@ -2,9 +2,13 @@ ### Table of contents -* [Running Chrome with a specific locale](#running-chrome-with-a-specific-locale) -* [Running Firefox with a specific locale](#running-firefox-with-a-specific-locale) -* [Contributing translations](#contributing-translations) +- [Localization in IPFS Companion](#localization-in-ipfs-companion) + - [Table of contents](#table-of-contents) + - [Running Chrome with a specific locale](#running-chrome-with-a-specific-locale) + - [Further resources](#further-resources) + - [Running Firefox with a specific locale](#running-firefox-with-a-specific-locale) + - [Further resources](#further-resources-1) + - [Contributing translations](#contributing-translations) IPFS Companion supports running in specific locales, with translations provided by the community via Transifex. diff --git a/docs/RELEASE-PROCESS.md b/docs/RELEASE-PROCESS.md new file mode 100644 index 000000000..d5049d605 --- /dev/null +++ b/docs/RELEASE-PROCESS.md @@ -0,0 +1,75 @@ +# Release Process +--- + +This process can be used to push a manual release to the [Firefox Add-Ons](https://addons.mozilla.org/) and [Chrome Web Store](https://chrome.google.com/webstore/category/extensions). Before you can do that you need to: + +- [Release Process](#release-process) + - [Tag a Release](#tag-a-release) + - [Build Release Artifacts](#build-release-artifacts) + - [Publish on Chrome Web Store)](#publish-on-chrome-web-store) + - [Publish on Firefox Add-Ons Store](#publish-on-firefox-add-ons-store) + - [Release on Github.](#release-on-github) + + +## Tag a Release + +- Bump `` version in `add-on/manifest.common.json` +- Create a PR for Release + - Generate and push the tag to github + ```sh + git tag v && git push && git push origin v # Don't forget the 'v' prefix + ``` + - Create draft release from https://github.com/ipfs/ipfs-companion/releases using the `v` tag + - Use github's auto release notes feature to fill release notes. + +## Build Release Artifacts + +- run `npm run release-build` +- `build` folder would contain three artifacts, one each for: + - brave + - chromium + - firefox +- Attach these assets to the draft release. + +## Publish on Chrome Web Store + +All Chromium-based browsers support install from Chrome Web Store. +Brave, Opera, and Edge do not require additional publishing step. + +- IPFS Companion Chrome Webstore: https://chrome.google.com/webstore/detail/ipfs-companion/nibjojkomfdiaoajekhjakgkdhaomnch +- Publishing requires your Google Account to belong to the IPFS Companion Maintainers Google Group (ask IPFS Stewards to be added). +- Go to Developer Dashboard and select publisher: `IPFS Shipyard`. +- Select `Package` from the left sub-menu. +- Upload the newly built package for Chromium [earlier](#build-release-artifacts). +- The new package goes to draft state automatically. +- Go to `Store listing` section from the left sub-menu. +- Click `Save Draft` and then `Submit for Review`. +- "Review" may take from a few hours to a few days. Google sends no email informing when new version is approved. +- Only way to check it is to inspect the version number on the store listing or Dev Dashboard. + +## Publish on [Firefox Add-Ons Store](https://addons.mozilla.org/) + +- IPFS Companion Firefox Add-On: https://addons.mozilla.org/en-US/firefox/addon/ipfs-companion/ +- Publishing requires logging into a [Developer Account](https://addons.mozilla.org/developers/) at Firefox Add-Ons site. The account needs to be marked as one of developers of IPFS Companion (ask IPFS Stewards to be added). +- Goto `Manage My Submissions` from the drop-down menu from your username. +- Select `IPFS Companion` item. +- On the left menu select `Manage Status & Versions` +- Open the latest one in a new tab because you'll need this for reference for copying listing details. +- Click `Upload a New Version`. +- Select the Firefox-specific asset generated [earlier](#build-release-artifacts). +- For `Compatibility` select both : + - Firefox + - Firefox for Android +- Optionally quickly check the validation report to see there are no blocking validations. +- Click continue. +- When asked: `Do you need to submit source code` select `yes` + - Go to Github Release and download .zip with Source Code for the release tag. + - Upload it to Mozilla. +- In the field asking for release notes just link to the release at Github +- Add Instructions/Notes for the reviewer (*Warning: if you forget, the release may be rejected during human review*): + - Reuse the explanation from the previous release (ask reviewer to run the `npm run release-build` so they can run the build in a Docker container and get reproducible result across platforms) +- The new build is published immediately, but it will be reviewed in a week by a real human (unlike Chrome Web Store), and can be taken down if it doesn’t meet the guidelines around privacy and reproducibility. + +## Release on Github. + +Release the draft release just created. That's it!