Reorganize docs and add contributing guides
This change introduces a reorganization of the information in the
README.md document, which has been split into several files in the
//docs folder, and adds the following information:
- //docs/contributing.md: New document containing information
about how to contribute to the project.
- //docs/developers/build.md: Add information about CHROMIUM_MV3
- //docs/developers/set_up.md: New document containing information on
how to set up the development environment.
- //docs/developers/add_feature.md: Blank document which will contain
info on how to add a new feature/option to the extension.
Fixes: #26
Change-Id: I44c69ccbc20e609c5416e08fe0ef3b7934080d17
diff --git a/README.md b/README.md
index 1ab9140..6373612 100644
--- a/README.md
+++ b/README.md
@@ -4,94 +4,30 @@
An extension which brings several enhancements to the Google Forums and the
Community Console.
-## Release cycle
-When the code in the `master` branch is considered to be stable, a release can
-be made. This is the procedure:
+For a list of features/enhancements, check out the
+[feature list doc](docs/features.md).
-1. Tag the last commit with a version number (in the format `vx`, where x is the
-extension's [version number](https://developer.chrome.com/extensions/manifest/version)
-for that release) by running `bash tagRelease.bash --version vx`. Note that the
-tag must be pushed to Gerrit after being created.
-2. Build the extension for both the stable and beta channels (this is explained
-in the next section). This will output a ZIP file for each release channel and
-each supported browser.
+## Information for contributors
+This extension is being actively developed, and everyone is welcome to make
+feature requests, report issues and contribute code changes.
-Afterwards, the release/build files must be submitted to the Chrome Web Store
-and addons.mozilla.org.
+In order to make feature requests or report issues, please do so at the GitHub
+issue tracker:
-### Submitting to the Chrome Web Store
-1. [Upload both release files](https://developer.chrome.com/webstore/publish#upload-your-item)
-to the Chrome Web Store, one for each release channel.
-2. [Submit both releases](https://developer.chrome.com/webstore/publish#submit-your-item-for-publishing)
-to be reviewed by the Chrome Web Store team, but in the case of the stable
-channel uncheck the "Publish automatically after it has passed review" option.
-3. Upload the beta release file to the
-[GitHub releases page](https://github.com/avm99963/infinitegforums/releases)
-under the newly created tag. Mark that release as a pre-release at GitHub.
-4. Wait until the beta release is reviewed and approved by Google.
-5. Test again the extension by using the beta channel. Check if the options have
-been transfered correctly from version to version, and wait some days (for
-instance between 3 and 5 days) to see if other people report issues with the
-updated version.
-6. If everything goes well, publish the update in the stable channel. The
-updated version should have already been reviewed by the Chrome Web Store team
-at this time.
-7. Update the release file in the GitHub releases page by removing the beta
-release file and uploading the stable release file. Also, remove the pre-release
-label.
+- [Issues · avm99963/infinitegforums · GitHub](https://github.com/avm99963/infinitegforums/issues)
-If during this process the release wasn't approved by Google or an issue was
-found during beta testing, a new release which fixes this should be created.
+To see a more exhaustive guide on how to contribute, and information on how to
+contribute code changes, please read the following doc: <!--It also includes
+links to resources which explain learn how the extension is built, how you can
+extend it, and how it can be built:-->
-### Submitting to addons.mozilla.org
-The procedure is similar to the one with the Chrome Web Store.
-
-@TODO: Add more details once the first version of the extension has been
-uploaded to addons.mozilla.org.
-
-## Build the extension
-A zip file with the contents of the extension, which can be uploaded to the
-Chrome Web Store and addons.mozilla.org, can be created with any of the
-following procedures (make sure to [install Go](https://golang.org) before
-building the extension, as it is needed during the build):
-
-### Using the release.bash script
-Run `bash release.bash -h` in order to learn how to use this command. To
-summarize, the command accepts the `--channel` and `--browser` flags (or their
-short versions `-c` and `-b`).
-
-As an example, if you wanted to create a ZIP file of the beta-branded extension
-targeted for Firefox, you would run `bash release.bash -c beta -b gecko`.
-
-### Using make
-You can also use _make_ to build the extension. This is just a wrapper for the
-`release.bash` command.
-
-Run `make all` to build the extension for all the available channels and
-browsers. You can also run `make {target}` where `{target}` is one of the
-following: `chromium-stable`, `chromium-beta`, `chromium-mv3-beta`,
-`gecko-stable`.
-
-Run `make clean` to clean all the release files (this removes the `out` folder,
-which is where the release files are saved).
-
-## Testing notes
-When testing the extension during development, you don't have to build the
-extension each time you want to import an updated version to Chrome/Firefox.
-Instead, run `go run generateManifest.go {browser}` once, where `{browser}` is
-`CHROMIUM`, `GECKO` or `CHROMIUM_MV3`, and this will generate a `manifest.json`
-file for the specified browser in the `src` directory. Now, you can load the
-`src` folder directly in the browser in order to import the extension, which
-removes the need to build it. When the `manifest.gjson` file is modified,
-you'll have to generate the manifest again.
-
-To test translations, you might want to set your browser's locale. This section
-tells you how to set the locale in
-[Windows](https://developer.chrome.com/extensions/i18n#testing-win),
-[Mac OS X](https://developer.chrome.com/extensions/i18n#testing-mac),
-[Linux](https://developer.chrome.com/extensions/i18n#testing-linux),
-and [Chrome OS](https://developer.chrome.com/extensions/i18n#testing-chromeos).
+- [Contributing to TW Power Tools](docs/contributing.md)
## Beta channel
+Before releasing updates to the stable channel, the newest versions are uploaded
+to the beta channel so they can be tested by everyone who's interested. This is
+another way to contribute to the project, because beta testing can make us
+notice bugs before they reach the stable channel.
+
The beta channel for Chrome is available
[here](https://chrome.google.com/webstore/detail/infinite-scroll-in-tw-bet/memmklnkkhifmflmidnflfcdepamljef).
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 0000000..114281f
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,76 @@
+# Contributing to TW Power Tools
+If you're here, thanks for your interest in contributing! There are many ways
+you can contribute, and you don't need any technical background for most of
+them, so don't feel shy! Any help, even if small, is very much appreciated.
+
+## Make feature requests and report issues
+If you have some fresh ideas or insight into how to make the extension better,
+or you've found a bug (sorry!), you can create a new issue at the GitHub issue
+tracker:
+
+- https://github.com/avm99963/infinitegforums/issues
+
+If you're reporting a bug, please consider specifying your browser and version,
+and maybe the Javascript console logs (open the Javascript console by pressing
+`[ Ctrl ][ Shift ][ J ]`) for the page where the issue occurred.
+
+## Contribute translations
+If you speak a language other than English, you can help translate the UI to
+your language!
+
+If you're interested in helping with this, please email me at
+`me [at] avm99963.com`.
+
+## Beta test the extension
+Releasing an update to the stable channel isn't always an easy task, because
+bugs might make its way. As new release candidates are tested in the beta
+channel before being promoted to the stable channel, this gives us a last chance
+to catch any bugs before the release. This is why it's essential that some
+people volunteer to beta test the extension.
+
+While using the beta version comes with the risk of coming across bugs, those
+are usually minor, and you have the opportunity of using newer features before
+everyone else!
+
+*** note
+**Note:** It isn't recommended to install the stable and beta version of the
+extension at the same time, as you might end up with duplicate injected
+components or weird results.
+***
+
+You can install the beta channel here:
+
+- https://chrome.google.com/webstore/detail/infinite-scroll-in-tw-bet/memmklnkkhifmflmidnflfcdepamljef
+
+## Contribute code changes
+If you're a developer and you'd like to contribute code changes, please feel
+free to do so!
+
+You can get started by reading the following docs:
+
+- [Set up the development environment](developers/set_up.md)
+- [Build the extension](developers/build.md)
+- [Add a new feature](developers/add_feature.md)
+- [How to test translations](https://developer.chrome.com/docs/extensions/reference/i18n/#how-to-set-your-browsers-locale)
+
+*** promo
+TODO(avm99963): add a link to webext's `manifest.gjson` documentation when it is
+created.
+***
+
+You can get a list of open issues which are recommended for first-time
+contributors here:
+
+- https://github.com/avm99963/infinitegforums/contribute
+
+These issues will let you get familiar with the codebase and are not too
+difficult to implement.
+
+You can also assign yourself any of the open issues which haven't been assigned:
+
+- https://github.com/avm99963/infinitegforums/issues?q=is%3Aissue+is%3Aopen+no%3Aassignee
+
+For your information, the following doc contains a description of the release
+cycle for this extension, and how it is performed by its maintainers:
+
+- [Release cycle](developers/release_cycle.md)
diff --git a/docs/developers/add_feature.md b/docs/developers/add_feature.md
new file mode 100644
index 0000000..c8e81b2
--- /dev/null
+++ b/docs/developers/add_feature.md
@@ -0,0 +1,2 @@
+# Add a new feature
+TODO(Issue #28): write this doc
diff --git a/docs/developers/build.md b/docs/developers/build.md
new file mode 100644
index 0000000..76a1175
--- /dev/null
+++ b/docs/developers/build.md
@@ -0,0 +1,51 @@
+# Build the extension
+A zip file with the contents of the extension, which can be uploaded to the
+Chrome Web Store and addons.mozilla.org, can be created with any of the
+following procedures (make sure to [install Go](https://golang.org) before
+building the extension, as it is needed during the build):
+
+## Using the release.bash script
+Run `bash release.bash -h` in order to learn how to use this command. To
+summarize, the command accepts the `--channel` and `--browser` flags (or their
+short versions `-c` and `-b`).
+
+As an example, if you wanted to create a ZIP file of the beta-branded extension
+targeted for Firefox, you would run `bash release.bash -c beta -b gecko`.
+
+## Using make
+You can also use _make_ to build the extension. This is just a wrapper for the
+`release.bash` command.
+
+Run `make all` to build the extension for all the available channels and
+browsers. You can also run `make {target}` where `{target}` is one of the
+following: `chromium-stable`, `chromium-beta`, `chromium-mv3-beta`,
+`gecko-stable`.
+
+Run `make clean` to clean all the release files (this removes the `out` folder,
+which is where the release files are saved).
+
+## Load the extension "without" building it
+If you're developing the extension, you might want to load it into your browser
+without having to constantly build it after each change. In order to do that,
+you'll only have to manually generate the manifest each time you change the
+`template/manifest.gjson` file (or only once if you don't change it, and once
+every time you pull new changes to your git clone).
+
+In order to do that, run `go run generateManifest.go {browser}`, where
+`{browser}` is `CHROMIUM`, `GECKO` or `CHROMIUM_MV3`, and this will generate the
+`manifest.json` file for the specified browser in the `src` directory. Now, you
+can load the `src` folder directly in the browser in order to import the
+extension.
+
+## About the _Chromium MV3_ target
+Chromium is working in a
+[new version of the manifest.json file](https://developer.chrome.com/docs/extensions/mv3/intro/),
+which also introduces some changes to the extension APIs. Eventually, all Chrome
+extensions will be required to have migrated to Manifest V3 (MV3), so in order
+to anticipate this change, a new experimental _Chromium MV3_ target has been
+added.
+
+This target is experimental in the sense that it isn't actually used when
+building the extension ZIPs which are uploaded to the Chrome Web Store (MV2 is
+still used), and because these builds aren't currently being exhaustively
+tested.
diff --git a/docs/developers/release_cycle.md b/docs/developers/release_cycle.md
new file mode 100644
index 0000000..feb9744
--- /dev/null
+++ b/docs/developers/release_cycle.md
@@ -0,0 +1,44 @@
+# Release cycle
+When the code in the `master` branch is considered to be stable, a release can
+be made. This is the procedure:
+
+1. Tag the last commit with a version number (in the format `vx`, where x is the
+extension's [version number](https://developer.chrome.com/extensions/manifest/version)
+for that release) by running `bash tagRelease.bash --version vx`. Note that the
+tag must be pushed to Gerrit after being created.
+2. [Build the extension](build.md) for both the stable and beta channels. This
+will output a ZIP file for each release channel and each supported browser.
+
+Afterwards, the release/build files must be submitted to the Chrome Web Store
+and addons.mozilla.org.
+
+## Submitting to the Chrome Web Store
+1. [Upload both release files](https://developer.chrome.com/webstore/publish#upload-your-item)
+to the Chrome Web Store, one for each release channel.
+2. [Submit both releases](https://developer.chrome.com/webstore/publish#submit-your-item-for-publishing)
+to be reviewed by the Chrome Web Store team, but in the case of the stable
+channel uncheck the "Publish automatically after it has passed review" option.
+3. Upload the beta release file to the
+[GitHub releases page](https://github.com/avm99963/infinitegforums/releases)
+under the newly created tag. Mark that release as a pre-release at GitHub.
+4. Wait until the beta release is reviewed and approved by Google.
+5. Test again the extension by using the beta channel. Check if the options have
+been transfered correctly from version to version, and wait some days (for
+instance between 3 and 5 days) to see if other people report issues with the
+updated version.
+6. If everything goes well, publish the update in the stable channel. The
+updated version should have already been reviewed by the Chrome Web Store team
+at this time.
+7. Update the release file in the GitHub releases page by removing the beta
+release file and uploading the stable release file. Also, remove the pre-release
+label.
+
+If during this process the release wasn't approved by Google or an issue was
+found during beta testing, a new release which fixes this should be created and
+the previous stable update should be canceled and superseded by the new release.
+
+## Submitting to addons.mozilla.org
+The procedure is similar to the one with the Chrome Web Store, except for the
+fact that the stable version is directly uploaded to the store.
+
+TODO(avm99963): Add more details here.
diff --git a/docs/developers/set_up.md b/docs/developers/set_up.md
new file mode 100644
index 0000000..650ce31
--- /dev/null
+++ b/docs/developers/set_up.md
@@ -0,0 +1,15 @@
+# Set up the development environment
+Before starting to develop, you must set up your device. This is what you must
+do:
+
+1. [Install Go](https://golang.org/doc/install). On Mac, you can install it
+with [Homebrew](https://brew.sh/) by running `brew install go`.
+ - This is because the build script uses a Go program to generate the
+ manifest.
+2. That's it! If you're using a Mac, you're out of luck, because you must
+perform some more steps.
+
+## Mac-specific configuration
+On a Mac, you must also follow these steps:
+
+TODO(Issue #18): add macOS steps