initial commit

.config/i3blocks/CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# How to contribute
+
+So you've written a blocklet for i3blocks and would like to share it with the
+community, great! Let's just set a few ground rules in order to get your
+blocklet included.
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
+interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
+
+# Directory guidelines
+
+1. A blocklet MUST be confined to a single directory and the name of the
+   directory MUST be relevant to the blocklet's purpose or core feature.
+2. A blocklet MUST be human readable.
+3. A blocklet MUST contain a `README.md` explaining what the blocklet does,
+   what its dependencies are, and any special instruction or setup required to
+   use it.
+4. A suggested i3blocks configuration MUST be included in an `i3blocks.conf`
+   file or within the `README.md`.
+5. Any non-obvious assumptions required to make the configuration work SHOULD
+   be included either in the `README.md` or as comments in the configuration.
+6. A blocklet's suggested command SHOULD be of the form
+   `command=$SCRIPT_DIR/myscript [args...]` even
+   if the script is a single line. The [args...] SHOULD be empty, in favor of
+   using injected properties.
+7. The command file (`myscript` above) SHOULD be the entirety of the
+   executable part of your blocklet, i.e. your code is a single script.
+8. The command file's name, SHOULD match the name of the
+   containing directory. E.g. `myscript/myscript`
+   is a good name, but `myscript/yourscript` is not.
+9. A blocklet SHOULD NOT have a separate non `i3blocks.conf` configuration
+   file. Any extra configuration (e.g. default colors, paths, etc.) SHOULD be
+   injected properties.
+10. A blocklet MUST include at least one screenshot of what it looks like in
+   action.
+11. A blocklet MAY require building/compiling, but if it does the build process SHOULD be
+   as simple as possible (preferably nothing more than running `make`)
+12. A blocklet SHOULD include a `LICENSE` file.
+13. A blocklet MAY include a `.gitignore` file.
+
+# Dependency guidelines
+
+1. Listing standard utilities as dependencies is OPTIONAL.
+2. If a blocklet requires a specific minimum version of a program, that program
+   SHOULD be listed as a dependency, and the minimum version SHOULD be listed
+   as well.
+
+# Pull request guidelines
+
+1. Every commit being merged in a pull request MUST begin with the name of the 
+   blocklet it concerns, .e.g. `myscript: update colors`
+2. A contributor with write access MUST NOT merge any pull request that he or
+   she created, unless there are no other contributors with write access 
+   currently active.
+3. Commit messages SHOULD be written in imperative form. E.g.
+   `myscript: add option to configure colors`, instead of
+   `myscript: added option to configure colors`.
+4. Commit message first lines SHOULD be 72 characters or less but descriptive,
+   and details MAY be added to subsequent lines.
+5. Commit details SHOULD write `Fixes: [issue]` or `Closes: [issue]` if
+   the commit is meant to fix/close an issue on the issues page.
+6. A pull request SHOULD contribute significant change to exactly one
+   blocklet. A bug fix or new injected property will usually be considered
+   a significant change.
+
+# Example workflow
+
+In case you have never made a pull request before, here is an example workflow.
+
+1. You write and test your blocklet called `myscript`.
+2. You write a `README.md` and `i3blocks.conf` to go with your script, make a
+   `screenshot.png` and put `myscript`, `README.md`, `i3blocks.conf`,
+   `screenshot.png`, and your favorite `LICENSE` into a
+   directory called `myscript`.
+3. You fork the i3blocks-contrib repository on github, and clone your fork of
+   i3blocks-contrib onto your computer with `git clone [your fork here]`.
+4. You copy your `myscript` directory to the top level of the cloned
+   i3blocks-contrib directory and `cd` to the top level directory.
+5. You `git add myscript` to tell git to track your blocklet's directory, you
+   will need to do this before every commit.
+6. You `git commit` and leave a commit message of the form
+   `myscript: add myscript, a short description of myscript`
+7. Perhaps you make a few last minute changes, and add another commit.
+8. You squash your commits into one with `git rebase -i` and follow the
+   instructions, leaving only your first commit and commits that were already
+   there unsquashed.
+9. You push your changes to your fork on github with `git push`.
+10. You navigate to vivien's i3blocks-contrib, click "pull requests" and
+   "New pull request". You click "compare across forks", then select the base
+   as vivien's i3blocks-contrib and the head fork as yours. You click
+   "Create pull request".
+11. The community makes some comments and suggests some things to improve before
+   your blocklet is accepted.
+12. You add and commit changes to your local copy, and then squash them as before, so
+   that there are only two commits besides those that were there when you first
+   forked, your initial commit and one representing all the changes made to
+   address community concerns.
+13. You push to your remote fork of i3blocks-contrib, and the changes
+   automatically get incorporated into the pull request process.
+14. A maintainer with write access to vivien's i3blocks-contrib decides your
+   script is ready to be merged and merges it in, possibly making minor changes
+   of their own in the process.
+
+Whenever you make a significant change to your blocklet or fix a bug,
+squash your local commits since your last pull request and replace the commit
+message with something of the form
+
+    myscript: what has changed since last pull request
+
+    More detailed description of changes, perhaps including:
+        Change 1
+        Change 2
+        Change 3
+
+Then push to your remote fork, navigate to vivien's, and make a new pull
+request.