Skip to content

Contributing

Jump to bottom Edit New page
Nycroth edited this page Aug 14, 2015 · 21 revisions

So you've written a blocklet for i3blocks and would like to share it with the community, great! The following document will do its best to lay out the process you should now take to add it to the repository. There are two classes of blocklets however.

The first are scripts that essentially filter the output of some command into an output for i3blocks. These blocklets can be accomplished in a string under the command= option of the i3blocks config and are called oneliners. The second is a blocklet with the need of logic (if, loops, variables, etc...). These blocklets are called full blocklets.

Oneliners

Oneliners are the easiest blocklet to make and even easier to share. Oneliners are aggregated directly in the project wiki.

To add your own, edit the Oneliners page by first creating an entry for it to the table of contents. Add a line * [[Blocklet Name|Oneliners#blocklet-name]] in alphabetical order to the list for your new blocklet. Next, locate the sections of the listed item below you on the table of contents. This is easiest if you search the name of the item below yours.

Above this section, create a section for your new blocklet by creating ## Blocklet Name. Leave a blank line and then write a single sentence to describe what your blocklet does. Next, another blank line and then create a bash code block with three backticks followed by the word bash. On the following line add your line of code followed on the next line by three more backticks (refer to other blocklets' example). Below this code, leave a blank line and then write a paragraph about your blocklet. Be clear and concise. How does it work? Does the instance variable do anything?

That's it. No screenshots for these. If someone is unsure what your script displays they will just run the command directly.

Finally, preview your changes and ENSURE everything is correct. Make sure the table of contents links correctly and that there are no spelling, grammatical, or formatting errors. Once double checked, add a commit message and commit your changes to complete the job.

Next, edit the sidebar. In here, add your script alphabetically under * **[[Oneliners]]** with the template, - [[Blocklet Name|Oneliners#blocklet-name]]. Again, commit these changes.

That's it. No need for pull requests or reviews. You have contributed your very first blocklet!

Full Blocklets

The process for contributing a new full blocklet goes more or less as follows:

  1. Fork the i3blocks-contrib repo on GitHub.
  2. Clone your forked repo to your local workstation.
  3. Create a new branch for the blocklet.
  4. Copy the i3blocks-contib/example_blocket directory found in the repo and rename it.
  5. Add your blocklet to the directory.
  6. Clone the i3blocks-contrib wiki to your local workstation.
  7. Copy the i3blocks-contrib.wiki/Blocklet-Wiki-Template.md file and rename it.
  8. Edit your blocklet's wiki entry, following the template's guidelines.
  9. Edit i3blocks-contrib.wiki/_Sidebar.md to add your new page to the list.
  10. Commit your changes to the wiki.
  11. Push your wiki clone to the main repo.
  12. Copy the top of your wiki entry into the README.md file in your blocklet directory.
  13. Commit your changes to your fork clone.
  14. Push your fork clone to GitHub.
  15. Submit a pull request for a code/wiki review and merge.

Don't worry about the vagueness of steps above. Each step will be broken down below to help you merge in no time. The remainder of this document reads as follows. First, a step by step guide with detailed breakdown is listed. Below that, the standards body that your pull request is expected to adhere to. If you're familiar with the basic fork-branch-edit-commit-push-request process of GitHub, most of this will be redundant to you. Instead, skip ahead to the repo standards section. Also, always double check and/or follow the Pull Request Checklist.

Flow Breakdown

The first rule of i3blocks-contrib is that we talk about i3blocks-contrib. If you have any questions, comments, concerns, or other material to discuss open an issue. Many of the long standing devs on the project are always happy to help regardless of your experience with the project. That said, everyone is better able to help when you have read the documentation and know what the problem you're having is.

The following assumes you have both an active GitHub account, git configured with your name and email, and SSH key(s) added to the site. If you do not, please acquaint yourself with the GitHub documentation.

Step 1

The first step of any work on the repo is forking it to your account. Do so by clicking the "Fork" button found at the top right of the repo main page.

Step 2

Next, you must clone the newly forked repo to your local workstation. To do this, open your terminal and change directory to the directory you wish to clone the repo into. Now type git clone [email protected]:$USERNAME/i3blocks-contrib.git replacing $USERNAME with your GitHub username. This will ask you to enter your SSH passphrase and once authenticated, will proceed to clone your forked repo. Finally change into the directory with cd i3blocks-config.

Step 3

We are now going to create a branch. Branching allows us to work on multiple changes at once. If you have multiple blocklets to submit, you will need one branch for each. Without a branch you will be working in the master branch. This won't be a problem at first. However, when you want to then make further unrelated changes despite having an open and unaccepted pull request, you will wish you were working on a branch. It is just best current practice in git to branch, change the code, then merge the branch into master. This rapid branching model is one of git's greatest strengths.

To create a branch type git branch $BLOCKLET_NAME, replacing $BLOCKLET_NAME with your chosen blocklet name. Next, type git checkout $BLOCKLET_NAME. You are now working on the $BLOCKLET_NAME branch. To double check, type git status. The top line will read "On branch $BLOCKLET_NAME".

STEP 4

When adding your blocklet, we will begin with the template directory to speed up the work. Copy the directory with cp example_blocklet $BLOCKLET_NAME. Then cd $BLOCKLET_NAME.

STEP 5

We will now be adding your code to the newly created directory. Simply copy the main script and any required resource files into the directory. For most blocklets, just copying the script into the directory is sufficient. We must also apply the correct permissions for the script. First type chmod 644 *. If the script is directly executable, then also type chmod 755 $BLOCKLET_NAME.

STEP 6

Now we will create a wiki entry for the script. First, change directory to the parent of the repo. Type cd ../...

Clone the wiki locally by typing git clone https://github.com/vivien/i3blocks-contrib.wiki.git. Then enter the directory by typing cd i3blocks-contrib.wiki.

STEP 7

Now we will create a wiki page for your blocklet. Do so by copying the template with cp Blocklet-Wiki-Template.md $BLOCKLET_NAME.md. Again, replace $BLOCKLET_NAME with your respective blocklet name.

STEP 8

Open the new wiki page in you preferred markdown editor and modify the page to reflect your script. Be through. To add screenshots, we encourage https://imgur.com to upload the images unless you have them already hosted on a personal/project website. GitHub may also be used to host the image, however at the time of writing, this functionality has been buried or removed.

STEP 9

Now open _Sidebar.md. Locate **Blocklets** :package:. Under this will be * **[[Oneliners]]** and then one - ... for each onliner blocklet. After this is the list of blocklets. Add your blocklet in alphabetic order to the list with the following template line, * [[Blocklet Name|blocklet_name]]. "Blacklet Name" should be the name of the blocklet in 1-3 words. This should be Capitalized. "blocklet_name" MUST be the same as the name of the wiki page, that is $BLOCKLET_NAME, and thus the same as the main executable and the directory. This specifies a link to the Wiki page.

Step 10

For this step, we will be committing your changes. First, are you sure you've double checked your work? Maybe sleep on it and reread it in the morning. You may notice a mistake better.

To commit your changes, first add the changes to the staging area by typing git add _Sidebar.md $BLOCKLET_NAME.md. Now check that the wiki hasn't changed while you worked. If you do not do this before you commit and the wiki has changed, you will need to squash a merge into your commit. To check for changes, type git status. You should see "Your branch is up-to-date with 'origin/master'." in the second line your the output. If you do not, you will need to run git fetch origin master then git merge origin/master. Next, commit your changes with git commit -m 'Add $BLOCKLET_NAME wiki entry'.

Step 11

To push up you changes is easy. Just type git push origin master. Never push with the force -f option. This will delete other's changes.

Step 12

Now we will create the README.md for your blocklet. First copy your wiki entry with cp $BLOCKLET_NAME.md ../i3blocks-contrib/$BLOCKLET_NAME/README.md. Then, cd ../i3blocks-contrib/$BLOCKLET_NAME. Finally edit README.md and delete from ### Usage to the bottom of the file and delete the maintainers line. That is, only keep the name, sceenshot(s), description, dependencies, and optional dependencies.

Step 13

To commit you changes, change into the i3blocks-contrib root with cd ... Next add all the changed files to git with git add $BLOCKLET_NAME/\* (The \* is intentional, it lets git do the globbing instead of your shell). Run git status and ensure no files untracked or not staged.

Now double check everything is ready!

To commit, type git commit. Your editor will open and you are free to add a commit message. See the standards for what is expected. In general your first commit will be only, $BLOCKLET_NAME: Add blocklet to repo.

Step 14

Now we will push your fork clone branch to GitHub. To do this, type git push -u origin $BLOCKLET_NAME. Unless you have touched something on GitHub, you shouldn't have an error pushing this.

Step 15

Now, go check the Pull Request Checklist. Double check that you have done everything. If you have, go to the main contrib repo by clicking the link below your repo where it says "forked from vivien/i3blocks-contrib". Click the green pull request button and submit a friendly message describing your blocklet for the team. We will do what we can to review your code and wiki entry soon and then agree to merge your branch into the repo. Again, thank you for sharking your blocklet with everyone in the i3blocks community.

Repo Standards

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.

Blocklets

  1. MUST be named in regards the purpose or core feature.
  2. MUST be named in all lower case with only the hipehen and underscore charecters. i.e. [0-9a-z_-]
  3. MUST be human readable and in source code form.
  4. MAY be written in any language (compiled, assembled, or interpreted).
  5. SHOULD NOT duplicate existing blocklets' functionality.
  6. SHOULD rely on $BLOCK_INSTANCE for making core selections.
  7. MUST NOT require root privileges for any reason.

Blocklet's Directory

  1. SHOULD be named the same as the core executable.
  2. MUST be self contained and hold all the blocklet's related files and resources.
  3. MUST contain a README.md.
  4. MAY include a LICENSE.md file that separately licences the blocklet from the main repo.
  5. MAY include a .gitignore file.
  6. MAY include a Makefile for the purposes of compiling the blocklet source.
  7. MUST NOT contain any superfluous files.
  8. MUST apply permission mask 644 to all files.
  9. MAY break rule #8 when the blocklet is a script that may be directly executed. In this case, permission mask 755 SHOULD be applied.

Blocklet's README.md

  1. MUST mirror the blocklet's wiki page from the top of the file up to but not including ### Usage but exclude the line of maintainers.

Blocklet's Wiki Entry

  1. The creation of a blocklet wiki entry is REQUIRED.
  2. MUST be accurate and up to date prior to any pull request.
  3. MUST adhere to the most recent version of Blocklet-Wiki-Template.md.
  4. SHOULD use https://imgur.com to host all screenshots.
  5. The wiki sidebar's blocklet list MUST be in alphabetic order.

Pull Requests

  1. SHALL contribute changes to only one blocklet.
  2. MUST be merged as a single squashed commit.
  3. Commit messages MUST begin with the name of the blocklet.
  4. Commit messages SHOULD be written in imperative form. E.g. myscript: add option to configure colors, instead of myscript: added option to configure colors.
  5. Commit messages first line SHOULD be 72 characters or less.
  6. Commit messages SHOULD use lines below the first to outline each change made in the commit.
  7. A contributor with write access SHALL NOT merge or push any changes they have made into the contrib repo.
Add a custom footer

Main Info 📖

Blocklets 📦

Developers 🔧

Clone this wiki locally