[Community Question] What's the relationship between the core, the scripts, and the wiki to you?

[ghost]

Inspired by #117, I'm wondering what everyone in the community (and of course @vivien) feels the relationship should be between the core, the included scripts, and the wiki both currently and going forward.

My feeling from working with this project is that the core is designed to be a lean mean interface from STDOUT to i3blocks.JSON. A sort of "less is more" UNIX approach. The included scripts were then there to provide the most often desired functionality to prevent everyone needing to implement their own. At the same time these scripts would serve as a starting point and example of what you as the user can do when writing your own (prevent the blank canvas problem). Then contrib was merged and I've been a little confused ever since. I've always wondered if the wiki should be for all the one-liners and tips/tricks or if there really are supposed to be links to full scripts in other repos/gists.

This said, I'm wondering if the following would make more sense:

Core: Keep on track. Keep core as simple as possible and no further. There are no performance issues or worries of overhead now so let's not feature bugger it up.

Scripts: Be liberal with inclusion to prevent every script needing it's own gist or repo. It also centralizes edits and updates. Next, utilize the Wiki as documentation on each of the scripts (a README in the script install directory pointing users there perhaps). Then, limit the included config to what would be a reasonable for a minimal config (think Window's task bar (date & time, volume, network status (Offline, LAN, Internet), and battery)). The use of the config as documentation should be dropped (a note inside to visit the Wiki would also make sense). The requirements to be included should amend the current guidelines with a few more to ensure quality scripts are included plus sufficient Wiki and internal documentation and duplication is limited while not discouraging innovation or support for smaller interest groups (font awesome, media players, sysadmins, etc.). These should also be written into a CONTRIBUTING.md. The use of the Wiki would also not preclude those who wish to utilize external repositories for their code (eg. applications that also integrate with i3blocks like my own RSS reader--shameless self-promotion--or others).

Wiki: Obviously, first an FAQ. Then, each script should be it's own page. A full script may not be quite complex enough to demand an entire page but it would serve for a clearer and easier way for users to navigate. The other benefit is that mods/patches can be documented for each included script without feeling like you're wasting space. A page for one-liners would then catch everything that needs at best, minimal explanation (similar to the current Wiki). Also, a separate page for tips and tricks such as the separator or how to install and use font awesome or powerline fonts. The user's config page should be cleaned up and be cleanly divided into just screenshots and full out config examples. Finally, a page with new page templates for scripts and other pages plus Wiki contributing guidelines.

I don't mind doing all of this work. It will give me something fun to do. So there's no worry about that.

What does everyone else think?

[zopieux]

Thanks for your dedication on this. There is real value in your suggestions. Here's some points I thought of.

• Scripts: I agree that a wiki is not the right place to put long contrib scripts on. Versionning is not as trivial as it is for core GitHub code repo, it's harder to cleanly organize pages hierarchically. I suggest using another repository eg. i3blocks-contrib or i3blocks-scripts so all the PR, discussions & issues are kept apart from core.
• Wiki: indeed we need more better resources to introduce i3blocks and all the cool things you can do with it. Having one page of explanation per script is great. We should think of a basic template (main points) to follow so it's easier to get started and people don't forget the important things. You already suggested such a thing actually, but we have to discuss what to put in it.

[ghost]

Love the idea of a dedicated i3blocks-blocklets repository. :+1: It would definitely make the core a simpler project (almost all PR are about scripts). Plus, users need not install every script with a basic install. Of course, there will need to be a few scripts in the core. But, that can be figured out.

I present the following Wiki template as a first draft. Please critique!

[ghost]

[script_name.ext](to file in repo)

Maintainers is for current maintainers, not authors. If you don't want to be contacted about supporting this script and Wiki entry, you are not a maintainer, regardless of your contribution history. Maintainers is alphabetic. If nobody is maintaining the script, use Maintainers: orphaned. If you as a user are reading this, DO NOT contact maintainers directly. Open an issue or pull request and @ mention the maintainers in your post (Github will alert them). There are likely others in the community that can and will help with your problem (don't worry if there are no maintainers). Also, your problem may be of interest to others both now and in future. If you find orphaned scripts, feel free to become a maintainer if you feel familiar enough with the code. Delete this italic text when posting. Maintainers: @jpleau, @Nycroth, @Zopieux

Screenshot(s) (Cropped) One per line, minimum of one

1 paragraph follows with information on the script and it's design goals. Why was it written? What does it do? DO NOT answer how it is used or works here!

Dependencies

• i3blocks Version >= 1.4
• Unicode Font Support
• Font Awesome
• boost-libs

Optional

• python3-feedparser

Usage

Remove any unused fields in the config below. Leave in ONLY fields that must be filled for your script to function (choosing any reasonable default is fine). Avoid modifying any fields that are not critical to your script running successfully (eg. color). Delete this italic text when posting.

[script]
#label=
command=script_name.ext -f -l -s
interval=30
#signal=
#full_text=
#short_text=
#color=
#min_width=
#align=
#name=
#instance=
#urgent=
#separator=
#separator_block_width=
#markup=
#format=

script_name.ext [-f [-l]] [-a] [-g] [-s]
    -f    Force execution
    -l    Leave alone
    -a    Always run
    -g    Use grep instead of internal
    -s    Suppress information

This is where everything else should go about the script. Examples would include:

• MUST be run with the -s flag for it to work with i3blocks
• SHOULD be run with interval=30 or less
• Is Pango mandatory? Optional? Unusable?

Or perhaps, a paragraph about how your dependencies work. For example, maybe this script only needs python3-feedparser if the -f or -a flags are used.

Perhaps you have a paragraph or two about internals of the program itself so that users can make minor configuration changes such as a hard coded colour or design choice without a patch or Github issue.

Another paragraph perhaps about how you could go about filtering the output with another program and a pipe? Explain how the clickable icons in the blocklet work? This section is similar to a man page for your script, so be through. You get the idea...

Examples

This is where some handy example usages may be placed (if needed/desired). This section will often not be needed (and thus omitted) but may be used here if it will aid usability.

Related Scripts

• [mutt_script.py](to wiki entry) - This version focuses on Mutt instead
• [script_nameng.ext](to wiki entry) - Forked to redesign the render engine

---

The included patch is for those wishing to make a patch contribution and should be unneeded when posting initially. Simply delete everything below the above horizontal rule when posting initially. At the very least, delete this italic text when posting.

Patch: Unicode Removal

Maintainers: orphaned Last Update: 2015-06-19

Screenshot(s) (Cropped) One per line, if any

t a/script_name.ext b/script_name.ext
index cafe476..f687073 100755
--- a/script_name.ext
+++ b/script_name.ext
@@ -80,7 +80,7 @@ def check():
             log.write(str(datetime.datetime.today()) + ' ' +
                       '(' + str(feed.get('status', '---')) + ') ' +
                       str(feed.get('href', 'No URL Available')) + ' - ' +
-                      str(['', 'Poorly Formatted Feed ~'][feed.bozo]) + "\n")
+                      str(['', 'Poorly Formatted Feed'][feed.bozo]) + "\n")

         if feed.get('status') != 200:
             continue

This is a few paragraphs about the patch. The patch MUST be git compatible. Now explain the who, what, when, where, why, and how of the patch. When explaining, write pretending that, following an update to the script, a user can no longer use your patch (you're no longer here) but wants to change the script themselves. Explain why the changes take place and what you roughly did. You can assume a user manually modifying the script is semi-literate in the language. Any secret sauce should be explained however. Also, patches should only be posted here if their goal conflicts with that of the script itself. For example, a patch to remove Unicode/Font Awesome characters makes sense. Think about contributing or forking the script first before adding your patch here. Wiki patches should always be a last resort as updates to the script require new patches to be created.

[zopieux]

A few style suggestions, feel free to take into account:

• Maintainers: @Foo, @bar, @baz instead of many lines
• no colon at the end of titles (we already know it's an introduction to something because, well, it's a title)
• optional dependencies in a separate list, under the sub-sub-title Optional dependencies

[ghost]

All fixed! :+1:

[jpleau]

I think this is a good idea !

A separate repository for all user-contributed scripts so we can keep core clean is something I'd be happy with. We should make a list of scripts that should be included in core, though. (ie: the ones that are enabled in the default config). Those scripts should stay stable, not have fancy dependencies, and be usable with the version of i3blocks they were shipped with (assuming we're running a release, not a development version from git).

It would also enable packagers for various distributions out there to package snapshots of that i3blocks-{contrib,scripts} repository so users could use those scripts directly from their distribution's repositories. (ie: pacman -S i3blocks-scripts, apt install i3blocks-scripts, etc).

We should get Vivien's blessing first before starting anything, though ! Once we get going I'll be glad to help with anything.

Cheers

[ghost]

Of course! This is all subject to @vivien's approval, no doubt. Thanks for the feedback.

Core scripts, from my opinion; would be volume, battery, network status (Offline, LAN, Internet), and date & time. The networking script would be a new one that provides only 3 levels of state, not info like IP address et al. from the current scripts. This mimics the traditional networking icon from most other desktop environments and sets a hard limit on its utility (see #117 for the ongoing networking saga :sweat_smile:). Other than that, a slimmed version of volume and the current battery script would make sense.

However, I'm still not happy with the networking idea. Any better ones?

[bar]

@Nycroth I'm not maintaining this :)

[ghost]

@bar, sorry about that bud. I'm betting this happens all the time. Want me to remove you? :laughing:

[baz]

Happens to me all the time too ;)

[ghost]

Yeah, a sorry to you @foo, @bar, @biz, and @baz. :bow: I'll go remove you from the template. Wish you all the best though.

[zopieux]

Haha, sorry guys :smiley:

[vivien]

Their are good ideas here guys, thanks for your implication. The core is pretty stable actually, I'll release 1.4 very soon (hopefully in a few hours) and work on this with you guys right after.

[zopieux]

Brace yourselves, BATMAN is in da place.

[vivien]

Yay! I just polluted the internet with the announcement of 1.4 on Reddit, G+ and Twitter... Now let's work on this new architecture.

I'll create a new i3blocks-blocklets repository (feel free to criticize the name) for contributed scripts. Indeed, this will lighten up the core scripts (I'd like to have only Bash and Perl as dependencies), while being more flexible for you guys to add new awesome scripts.

For this new repo, I may plan to give write access to a few active contributors and maintainer. With a few commit rules, this might do the trick.

A single documentation page per script is a need. The wiki is nice, but a Github-rendered README.md file within the source might look good too. Although, this would implies each script to be in its own folder, i.e. battery/battery.sh and battery/README.md. Would that be overkill? On the other hand, the wiki reduces noice a lot (avoid fixup commits for typos and such). What do you think?

[kb100]

I like the idea of having a separate repo for blocklet scripts. I also think it is necessary for each blocklet script to have its own directory in case the script has multiple files and to avoid naming conflicts. As for managing the number of small commits, I don't think this is a problem. Trust contributers to squash small commits before pushing to the main repository.

[vivien]

I agree with you! @Nycroth what do you think? There can also be an example or template folder in that repository.

[zopieux]

I suggest the following structure for i3blocks-blocklets:

README.md   # main readme
blocklets   # main subfolder so we don't clutter repo root 
├── battery
│   ├── battery.sh
│   └── usage.md
├── microphone
│   ├── microphone.sh
│   └── usage.md
├── mpd
│   ├── mpd.sh
│   └── usage.md
├── network
│   ├── network.sh
│   └── usage.md
└── volume
    ├── usage.md
    └── volume.sh

I'm not sure about the usage.md though. Neither the name nor the format. Maybe we could use a generic format that compiles to man and Markdown (there are plenty). Can you think of other non-source files that would go under each blocklet folder?

We should also plan how maintainers would want to package this for their distrib and adapt to that. I, for one, would put this under eg. /usr/share/i3blocks/blocklets, without the main README.

[jpleau]

@Zopieux

Structure looks good to me ! As @vivien suggested, maybe adding a "template" or "example" folder could be useful.

For the installation folder as long as it is customizable this looks good to me too. (I think on Debian/Ubuntu we'll have to use something like /usr/share/i3blocks-blockets, to not use a folder already owned by another package).

Also, I would include the main README as well, there is no reason someone installing the package doesn't have access to this documentation :)

[vivien]

@Zopieux I'm fine with that except that I'm not sure if Github renders automatically a Markdown file not named /readme/i. Maybe usage.md will have to be README.md.

[zopieux]

@vivien Any .md files will be rendered in GitHub (random example).

[vivien]

I meant within a directory view, like this: https://github.com/vivien/modulo/tree/master/examples/irc

[ghost]

Haha, I stop watching GitHub for a day and all the fun begins. :stuck_out_tongue_winking_eye:

Everything so far sounds wonderful. For the core blocklets, might I suggest dropping Perl as a dependency? I know most people have Perl, however, the battery script (only Perl script) could just as easily be written in Bash. It only pipes the ACPI tools query into a few equations. I'm more than happy to leave it, but present for consideration: If we want to have a battery script, an ACPI tools free alternative will be needed anyways (assuming we don't want that dependency also).

@vivien, I would strongly encourage separate folders. No matter how complex any single blocklet is, they all work the same from a management point of view. @Zopieux, may I suggest the following layout:

CONTRIBUTING.md   # info for devs who are new to contributing
README.md         # main readme
configure         # program for users to select blocklets to install/update/uninstall
makefile          # main project makefile
_blocklet_example/
├── makefile
└── README.md
battery/
├── battery.pl
├── makefile
└── README.md
microphone/
├── microphone.sh
├── makefile
└── README.md
mpd/
├── makefile
├── mpd.sh
└── README.md
network/
├── makefile
├── network.sh
└── README.md
volume/
├── makefile
├── README.md
└── volume.sh

CONTRIBUTING.md is a means of informing new devs how to contribute. It will cover the prerequisites of submitting a pull request but point to the wiki for a full project overview.

README.md The main one will discuss the project. For the blocklet README.md, this will mirror the opening of the Wiki for the blocklet up to but not including the Usage section. It will only have one screenshot, no maintainers section, and the title link will be dropped and instead the Wiki URL will be placed at the end on a new line. This section of the Wiki is least changed and would best introduce a new blocklet to a user without providing details they wouldn't need when choosing to install the script. It means Wiki edits likely won't require a separate README.md edit. At least, that's my opinion. Always excited for feedback. The reason it's a README.md is because GitHub displays this if it finds it in a directory. However, this can both be read by the user from the command line and our configure program (if we want this) in more or less plain text.

_blocklet_example/ contains everything a dev needs to submit their blocklet. Copying and renaming the example folder, adding their code, then modifying the README.md and makefile will be all they need (usually). Finally, they create their Wiki entry and submit a pull request. The reason for the preceding underscore is visual difference, sort order, and so configure can filter this from actual blocklets.

I have toyed with the idea of man pages for blocklets but it feels like it wouldn't be worth the trouble. First, man pages suck to edit. So devs often use other formats to convert to man pages. Each of these are external dependencies. We could mandate a standard, we could mandate compiled pages be present (or both). However, blocklets would be in section 7. They aren't (usually) system commands. People may check the man, but I'm not so sure they'll look for the correct page first. They'll expect them to be in a single man page for the package they installed (eg. apt install i3blocks-blocklets;man i3blocks-blocklets). Sure, they may hunt or check the install log. Likely, they'll just visit the package associated webpage when they don't find that man page. Directed to either the repo root folder or the repo Wiki, they will find the info they want. The info is already here and editing is faster with no reviews. Plus; links to further reading, images, and user contributed examples all reside in the Wiki. It would duplicate the work, often annoy devs, and not be fully used. I know forcing people to visit GitHub is not fun, but I'm feeling like it'll be less bad than dealing with man pages for every blocklet. If others often use man pages for bundle packages (git, aircrack-ng, postfix, zsh etc.) feel free to correct me. I just resort to Wikis and online documentation when there are many components and pages needed.

makefile and configure... I know Make gets a bad rapport, but it is a POSIX standard, it is installed by default for most distros and BSDs, and it isn't going to be complicated for blocklet devs (given a template to follow). The reason I thought this would be ideal is that each blocklet is free to demand it's own installation needs. Sure, most just need to be copied to the default install point after checking dependencies, but this leaves the most flexibility. Now, the really cool part: any portion of the repo can be installed by a user using the primary make file. They may select to install all or selected subsets of blocklets. Plus, each can be installed/updated/uninstalled independent of the rest. Install and update only the blocklets you use. Plus, use either the main makefile or a blocklet's makefile directly. Simple for a user and package maintainer. Yes, copying the entire folder somewhere is easier, but not at all flexible. A blocklet in a compiled language for example: annoying. I suggest the make approach for a way of standardizing blocklets. There is no telling how complex some blocklets may be and this keeps simple blocklets as simple as possible while accommodating broader needs. What do others think?

As always, feedback always appreciated.

[ghost]

I'm also unable to read. :anguished:

[zopieux]

As always, feedback always appreciated. :no_entry_sign: Nycroth closed this an hour ago

Well that was fun.

[ghost]

No feedback for you!

[ghost]

@dmarcoux uses ~/.config/i3blocks/blocks/ for his blocklet scripts. I like this. I think this is a really great idea. I think it encourages people to edit and play with the scripts. Just brought it forward. Not sure how everyone feels about the idea.

(I'm moving my config and scripts thanks to this!)

[ghost]

So, I'm assuming there's no feedback... Would starting with the Wiki split make the most sense? Or should the blocklet's repo be done before the wiki?

[zopieux]

That would be nice if @vivien could create the seconday repo and add some +w contributors so we can at least start stuffin' around and see what's the best direction this should take. Like an alpha repo you know.

---

Btw sorry I missed your comment, README.md is indeed the only file that's going to be rendered in GitHub directory view, so we may as well change the name to that.

[ghost]

Sounds great!

[kb100]

I second using ~/.config/i3blocks/blocks for where to put script folders, which contain the scripts and their configs. I suggest making this the standard. I also suggest that contributed scripts SHOULD include a Makefile that installs to this directory. E.g. My script i3blocks-usb should install to ~/.config/i3blocks/blocks/i3blocks-usb. Then we would suggest that users make BLOCKS_DIR variable for i3blocks.conf and use

[scriptname]
command=$BLOCKS_DIR/scriptname/script.ext

or if command is not specified, it is assumed that the user means

[scriptname]
command=$BLOCKS_DIR/scriptname/scriptname

[ghost]

I love the concept @kb100, though the double script name is annoying me. I'm wondering if using ~/.config/i3blocks/blocklets/i3blocks-usb would cause problems. Then, if a script also needs a directory they may also create an optional ~/.config/i3blocks/blocklets/i3blocks-usb.d/. This way, $BLOCKLET_DIR/$BLOCK_NAME would be an acceptable call for most blocklets (ie. in the default section).

However, some may argue that $XDG_DATA_HOME/i3blocks is the more appropriate place. What say you all? This removes the need for a blocklets directory in the config directory as i3blocks does not need a data folder. Plus, it is spec correct.

[zopieux]

I'm not sure why you are discussion the location of the blocklet dir, as it is up to the user to chose that. How is it relevant to the wiki thing?

[kb100]

@Zopieux If the user wants to deviate from the standard that is his choice, and scripts will not be able to assume that they live in any particular location. However, there is organizational benefit to setting a suggested location. E.g. for system wide configuration files, it is a standard to put them in /etc. You don't have to put them in /etc, but unless the user specifically wants to put them somewhere else, it's nice to gather all the system wide config files in /etc.

This is relevant to the wiki because if the wiki is replaced with one or more scripts repositories, it will help developers (new contributers especially) to have existing scripts well-organized.

[ghost]

The Wiki and this are more or less separate. The wiki is only half of the split (as far as I understand). The other half is producing a set of standards for contrib scripts to make merging all of the scripts more uniform and user usage, just as predictable.

If we encourage a user owned folder for contributed script's installation point, users can play much more readily with them. Scripts in /usr/libexec/i3blocks/ are effectively cut off from tampering. On the other hand, installing them in /usr/libexec/i3blocks/ works just as well. It's already used by i3blocks proper and means the two repos don't create a rift within the project. Only toying with an idea. Feedback against such a proposal is also quite helpful.

Edit: I'd probably lean towards just using /usr/libexec/i3blocks/i3blocks-usb with optional /usr/libexec/i3blocks/i3blocks-usb.d/ as the standard.

[vivien]

I created https://github.com/vivien/i3blocks-contrib.

Here are some random things I'd like to keep in mind.

keep it simple. I can understand the need to standardize the blocklets and make it easy to install single blocklet (thinking about @Nycroth's makefiles), but most users are lazy. The use case will certainly be the following: they will browse the contrib repo, look at a script/screenshot, grab the raw file and that's it. We should priviledge access to information (config, screenshot) before setting up any framework or similar architecture. No premature work.

Every modification must be PR. For people gaining write access to the repo (maintainers): 1) no direct push. 2) do not merge your own PR. So A pushes a PR, B reviews and merges.

While I do want a linear history in the core repo, I do not care about linear history vs. merge commits (introduced by the merge button) for the contrib directory. But I do care about a clean history. That means no ten tiny commits where each fixes the committer's inability to use git correctly in the previous commit. So atomic commits, with clear and clean commit messages.

And for sure, for consequent changes, discuss it publicly with others first (gitter or a github issue).

In terms of code, I'd go with the main .md files, one directory per blocklet with its README.md file for a config example an eventual screenshot (or why not a like to somewhere else for more info). No uneeded code/files.

Write access can be given to an active code contributor, if we feel the need (someone won't gain write access because (s)he contributed his/her own single blocklet).

Finally, this is just a consensus I'd like contributors to follow. If you have an objection, please say so. Otherwise, you know what mess can result from this push festival!

This contrib folder is kinda beta. the repo name, layout, etc. are subject to change in the future when we'll be figuring out the real needs.

Does it look ok?

[ghost]

Yeah, everything is perfect from here. I agree, no premature work and pull instead of push for sure. I've been without internet for a few days so I'm catching up but I'll begin working on the repo tomorrow.

So far, it looks like a blank repo. lol Can't wait to help out. :smile:

[vivien]

Indeed, I'll move the non-default scripts asap.

Also, I renamed the repo to i3blocks-contrib, because it makes it clear that it regroups the community contributed blocklets.

Seeing i3blocks-blocklets may be confusing to someone, wondering if it is a required dependency or not (especially since the core will also include a few default scripts). And Googling "contrib" site:github.com shows that it is quite conventional.

I'm excited about this new repo, this topology works really well with active and fair maintainers!

[zopieux]

Great news! Can't wait to contribute.

[ghost]

I have reduced all core script dependencies to /bin/sh, coreutils, and AWK/Sed. I have also removed the need for scripts to store files (i.e. bandwidth). I have also stripped embedded colours.

I've narrowed the list to bandwidth, battery, cpu_usage, iface, memory, volume, and wifi. I have removed disk and load_average as both are one line commands. disk is df through awk and load_averages just read /proc/loadavg.

The changes are in my staging area while I wait on some feedback about the layout of /sys/class/power_supply. I have a forum post in the Arch Linux Forums looking for people to send me info on the folder's layout and contents. The other four are in contrib already and make good contrib candidates I'd believe.

How's everyone's feeling on these scripts becoming the core? Unfortunately battery is still pending. Once that's done, I'll submit a pull request so everyone can review the scripts. If I don't have info on batteries by midnight I'll commit what I have to my repo and submit the pull request just so everyone can start looking at them and comment over there.

If everyone also feel the same way, I'm thinking we should take a copy of the scripts to contrib to act as a foundation for adding often desired features such as fonts, colours, and extra options.

Wiki is still in progress. I'll report back when I'm done with that.

[ghost]

Pull request #125 is now open for the scripts. I have also begin the initial movement of the Wiki. Let me know what you think of either or both. :wink:

[ghost]

Quick update: Not dead or abandoning. Just really busy. I will be back to coding/documenting soon (few days). Promise.

[ghost]

Status Update: I did just delete the Blocklets.md page from the wiki. I have already ported the oneliners over to the i3blocks-contrib wiki. I will now begin contacting all authors of the other scripts about submitting them to the contrib repo. I still have a backup and the wiki repo history (wikis are managed through git) still has it of course. Fear not. :smile:

[ghost]

Status Update: Wiki is basically done. The current blocklet wiki entries are outstanding. However, beyond that, all the other pages seek proofreaders. Thanks in advance.