Contributing

Blocklet Contributions

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.

To begin, you should know that this project distinguishes two classes of blocklets. 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 scripts.

Below, these two blocklet types have the methodology for submitting outlined. However, it is your responsibility to ensure your work meets the Repo Standards regardless of what is discussed below. The authors of this article have done their best to ensure the methodology will yield a standards compliant submission, but mistakes are inevitable. If your submission dose not meet the Repo Standards, your pull request will be held until corrected.

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 section of the item listed below you in 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 inserting ## Blocklet Name. Leave a blank line. Next, write a single sentence to describe what your blocklet does. Leave another blank line. Now, 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. Finally, 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.

That's it. No need for pull requests or reviews. Your submission will be reviewed periodically by other wiki maintainers and added to the sidebar.

Scripts

The process for contributing a new script 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-contrib/example_blocklet directory found in the repo and rename it.
5. Add your blocklet to the directory.
6. Edit the README.md file and add a LICENSE.md if desired.
7. Commit your changes to your fork clone branch.
8. Push your fork clone branch to GitHub.
9. Submit a pull request for a code review and merge.

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 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 breakdown goes into excruciating detail at times. If you feel confident in the typical fork-clone-branch-edit-commit-push-pullreq GitHub routine, feel free to only skim the contents below. Refer to the Repo Standards at all times no matter how well you read and follow instructions.

The following assumes you have an active GitHub account, git configured with your name and email, and your 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. Once authenticated, git will proceed to clone your forked repo. Finally change into the directory, type cd i3blocks-contrib.

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, deleting the branch. This rapid branching model is one of git's greatest strengths.

To create a branch, type git checkout -b $BLOCKLET_NAME master, replacing $BLOCKLET_NAME with your chosen blocklet name. Your $BLOCKLET_NAME MUST be named using only lower case, numbers, hyphens, and underscores (i.e. [0-9a-z_-]). 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, typing cp -r example_blocklet $BLOCKLET_NAME. Then, type 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, type chmod 755 $BLOCKLET_NAME.

STEP 6

Now edit the included README.md file that was inside the directory. Try to follow this template to keep the project's documentation consistant. If you want to use a license other than the project's unifying LICENSE, feel free to include your license as LICENSE.md within your folder.

Step 7

To commit your changes, change into the i3blocks-contrib root directory, type cd ... Next add all the changed files to git with git add $BLOCKLET_NAME/. Type git status to ensure all files are tracked and staged that should be.

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 Repo Standards for what is expected. In general your first commit will be only, $BLOCKLET_NAME: Add blocklet to repo.

Step 8

Now 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 9

Finally, go to the main contrib repo. 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 entry soon and then agree to merge your branch into the repo. Again, thank you for sharing your blocklet with everyone in the i3blocks community. You blocklet may now go on to be used by hundreds of i3blocks users.

Project Maintenance

You are willing to help us keep the project in tip top shape? AWESOME!!!

How can you help? So many more ways than you know.

The first place everyone can help is the wiki. Now, you may ask, "How do I begin maintaining a project Wiki?" First, know that you cannot destroy the wiki. The wiki is built on git and all changes are commits. This means every change can be rolled back. However, anyone is free to make changes as large or small as they need without fear that their changes will be reverted. Unless the change is malicious, we welcome every change. Often, first wiki contributions are like first code contributions. They are small syntactical changes like fixing a grammatical or spelling mistake. Just because the number of changes is small, does not mean the impact is as small. Nothing puts people off faster than these tiny errors. So, if you're reading and something doesn't read naturally, fix it, then change to preview mode to continue reading. If you spot more, make the changes within the same commit to cut down on Fix readability commit messages. Remember, when documentation is predictable and uniform it helps users locate and utilize information faster. Lastly, the FAQ is always lacking.

Do you know another language and want i3blocks to be better usable by non-English speakers? Feel free to begin an effort to translate for the project. We are more than happy to have your help and expertise. Open an issue and let us know how we may assist your work.

Is code your native language? We welcome every coding fix from lint compliance to PEP8 and well into test development and refactoring. See a bug, don't know the language, open an issue and another contributor will surely be able to help.