Contributing

The project wiki is a community driven effort. Everyone is welcome to commit any change they see fit to it. However, please aquaint yourself with the Repo Stardards first.

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 full blocklets.

Below, these two blocklet types have the methodology for submitting them 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.

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. Your submission will be reviewed periodically by other wiki maintainers and perhaps even amended to add features.

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. Copy the Blocklet Wiki Template markdown to your new wiki entry.
7. Edit your blocklet's wiki entry, following the template's guidelines.
8. Copy the top of your wiki entry into the README.md file in your blocklet directory and edit it.
9. Commit your changes to your fork clone branch.
10. Push your fork clone branch to GitHub.
11. Submit a pull request for a code/wiki 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 both the Repo Standards and the Pull Request Checklist at all times no matter how well your 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-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, deleting the branch. 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. Your $BLOCKLET_NAME MUST be named using only lower case, numbers, hyphens, and underscores (i.e. [0-9a-z_-]). 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, typing cp 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 we will create a wiki page for your blocklet. Do so by editing and then copying the Blocklet Wiki Template. Now click "New Page" at the top of the wiki. Begin by naming the entry $BLOCKLET_NAME and pasting the template into the content section. Remember, $BLOCKLET_NAME is the name used by the main executable and blocklet directory verbaitum.

STEP 7

Begin by editing the template. Be through. To add screenshots, we encourage using 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, this functionality is slightly complex, requiring you to add them through an issue. Hence, we encourage Imgur.

Once finished, double check your work! Maybe sleep on it and reread it in the morning. You may notice a mistake better. If you are SURE you have previewed it and everything is wonderful, add a commit message and commit your changes.

Step 8

Now we will create the README.md for your blocklet. Edit the README.md in your blocklet's directory. Replace each section in the README.md with the contents from your wiki entry. That is, copy the name, sceenshot(s), description, dependencies, optional dependencies, and installation sections.

Finally, change the link at the top on the blocklet name from, https://github.com/vivien/i3blocks-contrib/tree/master/$BLOCKLET_NAME to https://github.com/vivien/i3blocks-contrib/wiki/$BLOCKLET_NAME.

Step 9

To commit you changes, change into the i3blocks-contrib root directory, type 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. 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 10

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 11

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 sharing your blocklet with everyone in the i3blocks community.