Friday, December 18, 2015

The Atom Editor - part II. - The Atom Packages

A Collection of Must Have Atom Packages


The Atom editor calls the extension plugins Packages. The packages can add a new functionality, extend the existing functions or completely replace them. Even the core functions can replaced by an external package.

How to Install Packages

Installing directly from the Atom Editor

It is really easy, in the Setting panel (Ctrl + ,) go to the Install section, search for a package and press the Install button.

Installing from Command Line

Alternatively you can install packages from command line using the `apm` command. Run `apm install package` to install the package. You can also pass multiple packages for mass installation.

Installing Starred Packages

You can mark a package with star - unfortunately only at the Atom web pages, not from the editor itself. Then you can install the starred packages with command "apm stars --install" command.

You can also install the starred packages from a different user. So if you want to install all my starred packages simply run "apm stars --user lslezak".

Note: It will install all starred packages, you cannot select individual packages or change the list before installation. So really check what the bundle contains!

Possible Problems

There are thousands of Atom packages available so it means there is a wide variety of packages and you almost sure find a package for a feature you miss.

Too Many Packages?

But that also means there might be several packages providing the same functionality, there might be forks of the same packages, there might be low quality packages... This is a similar situation like with Rubygems, you have to spend some time searching for the best option.

You can use the download number as a very roughly indicator, a high download number usually means the package is good. (Obviously this metrics does not work for the newly published packages or for very specific packages...)

Conflicts

Another drawback of too many packages is that there might be conflicts between packages by chance. The keyboard shortcuts can easily get in conflict because there are not many possibilities for unique and simple shortcuts.

If a shortcut does not work for you then look whether it is actually defined properly in Settings -> Keybindings section. Or you can press Ctrl+ . (dot) to display the keybinding resolver which displays all actions for the pressed keys.

There are two possibilities how to resolve a conflict:
  • Simply ignore the conflict and use the command panel (Ctrl + Shift + p) for selecting and running the action.
  • If you need to run the action often and you really want to have a shortcut then you can disable the keyboard shortcuts for the conflicting package. If you need the shortcuts for the conflicting package you can remap them in your config file (there is a link at the top of the Keybinding settings page).
If the packages conflict at the UI level (using the same UI element, that can happen if you install another fork of a package) or at the program level then you should probably report an issue at GitHub and ask the maintainers to solve the conflict.


Generic Packages

[Note: Some screenshots are linked from the project pages.]
  • open-recent - Adds a new submenu with the recent files and projects, helps when you often switch between multiple projects.


  • local-history - Keeps a copy of each file when saved, can help you if you are experimenting and you want to get some change from the history. When you are testing something you usually do not commit every change to Git (you would need to clean them up later) so if you need to have a fine grained history without Git commits this tool can help you. The changes are displayed in a diff tool (meld by default) so you can easily choose which specific parts should be reverted back.


  • sync-settings - Backs up the Atom settings to cloud (GitHub's Gist) which can be later restored. You can easily share the configuration, packages, snippets, etc across several machines (e.g. a desktop and a laptop).
  • term3 - Run terminal directly in an Atom tab, run commands without switching to a different window.

Editor Packages

  • revert-buffer - Drops all changes and reloads the current file from disk. You can close the file without saving and then reopen it but you would need to file the file in the tree and it would loose the current state (tab position, cursor position).
  • change-case - Easily change the case (camel, snake, upper, lower...)
  • toggle-quotes - Easily switch between single quote (') and double quotes (")
  • highlight-selected - Highlights the selected word in the file, helps with locating functions and variables in the file.
  • minimap - Displays a miniature of the file for easy navigation.

Code Completion

Git Packages

  • atomatigit - Adds an optional side bar with Git status and provides some shortcuts for Git commands (stage, commit, push...):



  • git-plus - Access to the most used Git commands


I currently combine both, git-plus has direct shortcuts while atomatigit is more interactive (e.g. you can select which changed files to stage and commit).


  • git-blame - Displays the "git blame" data next to the text:



  • git-history - Displays a commit (diff) from the history of the current file (or a full version)

  • git-log - Displays a graph with the Git commits




Additional Language Packages


These packages provide syntax highlighting and support for other file formats and programming languages which are not included in the default set:
Of course, you can find support for many more languages, just check the available packages.

Ruby Packages


These packages can help you with Ruby development.
  • ruby-block - Highlights the matching block at the cursor. When you place the cursor at `end` keyword it highlights the matching `do` or `if` line.


  • ruby-block-converter - Easily convert between single line `{}` and multine `do...end` Ruby blocks.

  • ruby-quick-test - Runs the test at the cursor, avoid running whole possibly long test suite when fixing just a single test.

Linters

Linters provide live code style checks and/or syntax checks.


  • linter-rubocop - There is also Rubocop linter, but unfortunately it requires a recent version of Rubocop (the version used by YaST is too old).

Building tools

For building the sources I basically found two systems:



I tried both and it seems that the "build" package is a bit better from the usability point of view. "build-tools" use more complicated keyboard shortcuts and require manual configuration while "build" tries to autodetect the tools used (scans for "Makefile", "Rakefile", etc...).

Web Development




  • pigments - Another color selection and visualization tool. (Note: I suggest to disable it and enable it only when editing a style sheet. The package treats numbers in a text like "bnc#123456" as a color specification and sets it as the background which looks weird...)


    • emmet - expands text like "ul.list>li.item*3" into appropriate HTML structure

    • rest-client - A simple REST API client for testing server responses, can be useful for testing the server response.

    TODO and FIXME Helpers

    • imdone-atom - Scans the project for "FIXME", "TODO" and similar comments. Displays a Trello-like dashboard where you can track the status. The drawback is that it adds some additional tags to each comment (to track the state) so it is not good for project where you do not want to change the code unnecessarily.


    • todo-show - Similar to the previous package, but only scans the project. On the other hand it does not touch the code.

    Miscellaneous

    I found some quite interesting plugins which nicely show the flexibility of Atom.

    • lcov-info - Displays code coverage overview and highlights covered and not covered lines. For Ruby you need LCOV coverage generator like simplecov-lcov Ruby gem.
      You need to enable single file output via "SimpleCov::Formatter::LcovFormatter.report_with_single_file = true" option and add the formatter. Unfortunately the generated coverage is saved to "./coverage/lcov/directoryname.lcov" while the lcov-info expects "./coverage/lcov.info" file. You have to move the file manually or enhance the task which runs the test.
    • markdown-scroll-sync - A nice enhancement for the builtin Markdown preview package. It keeps the editor position in sync with the preview when scrolling and moving the text.


    • docblockr - help with writing the documentation comments, scans the function methods and generates a template. Unfortunately the support for Ruby is missing... :-(



    • travis-ci-status - Displays a Travis build status icon in the panel. On click it displays details with a direct link to the Travis build.



    To be Continued...


    The next time we will look at the "hackability" of the Atom editor...

    Monday, December 14, 2015

    The Atom Editor - part I. - Introduction

    The Atom Editor

    For the 13th SUSE HackWeek I chose the Atom Editor as the topic.

    I wanted to get familiar with it and to learn how to customize it and how to develop new features.

    Atom Overview


    For the quick overview of the Atom features just watch this video:


    If you have more time you can watch this longer video:


    Installation

    Installation is quite easy, there are pre-built binary packages for the most used Linux distributions. If there is no package for your distribution or it does not work for you then you can build Atom from the sources.

    Fortunately for the openSUSE distribution is it easy, just download the RPM package from the main page. It has been built for Fedora 21 but it works without any problem in openSUSE Leap 42.1. (I have tested an older version also in openSUSE 13.2 and it was fine so it should work there as well.)

    Setup

    I suggest to switch from the default white-on-black scheme to more usual black-on-white which is used by most desktop applications and make switching to the other applications (like a web browser) more eye-friendly.

    At the configuration tab (Ctrl + ,) go to the Theme section and select Atom Light as the UI theme and One Light as the syntax theme. You can try the other themes or you can download some new one in the Install section as shown in the videos above.


    The Atom Features

    Here is a short summary of the features which I found interesting during the short testing. I do not mention the usual editor features and I likely overlooked something. You can also see some features in the videos above.

    • The Command Panel (Ctrl+Shift+P) is probably the most important feature. It displays all known commands (the core commands and also from all enabled plugins) with a keyboard shortcut if available. There is also a quick search for looking up.
      So if you cannot remember a shortcut or you do not know where to find a command just simply type it into the search bar and Atom will list all (even fuzzy) matches.
    • The Atom authors say it is a hackable editor. I can confirm this, you can very easily change the look or layout or add new features. But let's go into the details in another blogpost...
    • Open at GitHub - if you are editing a file which is stored at a GitHub repository you can easily open it in web browser. That's useful if you want to send a position in the code via IM, mail etc...
    • Live Markdown preview can be displayed while you are typing. This helps a lot with the correct formatting.

    The Atom features can be easily extended by plugins, let's look at them later.


    Documentation

    You can find the detailed user documentation here.


    To Be Continued...

    Next time we check some Atom plugins which extend the basic functionality.


    Monday, April 27, 2015

    SUSE HackWeek12 - YaST: Replacing Travis by Jenkins

    Replacing Travis by Jenkins for YaST


    I decided to look at the possible Travis replacement as my Hackweek 12 project.

    Currently we use both Travis and Jenkins for continuous integration in YaST projects. Unfortunately there are many disadvantages with Travis which require additional work or limit us what we can run in a Travis job. See the hackweek project for the pros and cons summary.

    The biggest Travis disadvantage is that the builds are run in a Ubuntu 12.04 system which is 3 years old and it's very difficult to find a recent compiler, Ruby interpreter, libraries,... for it. 

    The Jenkins advantage is that it runs on our server and we can run the latest openSUSE very easily and avoid the problem with porting YaST packages to Ubuntu and backporting the development tools.

    Jenkins Plugins


    I found out that there are several Jenkins plugins which could be used to replace Travis with Jenkins:

    You can install the plugins in your Jenkins instance like this:
    • Login into Jenkins
    • Go to Manage Jenkins -> Manage Plugins
    • In the tab Available select plugins GitHub Plugin, GitHub pull request builder plugin and Embeddable Build Status Plugin and install them

    Configuring the GitHub Plugin

    • Generate a new access token at GitHub, select public_repo and repo:status. If you want to allow automatic webhook setup select write:repo_hook (you can add/remove the permissions later).
    • Add the token to Jenkins -> Manage Jenkins -> Configure System -> GitHub Web Hook section -> OAuth token field
    • Put the same token to the "GitHub Pull Request Builder" section, "Access Token" filed.

    Create a new Jenkins job for building commits (pull requests are handled separately):

    • Select Freestyle project
    • Put the Github URL (https://github.com//) to the GitHub project filed
    • In the Source Code Management section select Git and put the same URL here
    • Make Branch Specifier field empty to build all branches
    • In the Build Triggers section - check Build when a change is pushed to GitHub
    • Add Build Step -> select Set build status to "pending" on GitHub commit
    • Add post-build action - Set build status on GitHub commit
    • Configure the other parameters of the build as needed
    See more details here.

    Configuring the GitHub Pull Request Builder

    • Add the created GitHub token to Jenkins -> Manage Jenkins -> Configure System -> GitHub Pull Request Builder section

    Create a new job for building pull requests:

    • Select Free style project
    • Put the Github URL (https://github.com//) to the GitHub project filed
    • In the Source Code Management section select Git and put the same URL here
    • In Advanced option set Name to origin and Refspec to +refs/pull/*:refs/remotes/origin/pr/*
    • Set Branch Specifier to ${sha1}
    • In the Build Triggers section - check GitHub Pull Request Builder option
    • Check Use github hooks for build triggering option
    • Set Commit Status Context to continuous-integration/jenkins-ci/pr (or something like that to have a different ID for pull requests and avoid clashing with the GitHub plugin configured in the previous step
    Set Admins or white list users so you do not have to manually trigger builds for trusted developers - the plugin avoids running trusted code at your

    Using Both Plugins in One Job?


    I tried to use both plugins in a single job to have less jobs but it did not work form me, the pull requests were not processed at all or it did not work at all.

    If you find how to solve it let me know...


    Coveralls Support?


    The question was whether coveralls code coverage can run also outside the Travis environment.

    I found out that it is possible, you just need to set the COVERALLS_REPO_TOKEN environment variable and some other variables containing the Git branch, build number, etc... See more details here.

    You need to store the token into Jenkins and set it during build.  (You can put the token directly into the .coveralls.yml file, but that's not a good idea for a public Git repository...) Fortunately there is a Jenkins plugin which helps with this, it can inject a secret in to a environment variable. The nice feature is that it can also filter the console output to make sure your password/token does not leak in the build output.


    The Current State


    I have created some experimental jobs to try the plugins, e.g. yast-registration-github-ci, yast-devtools-github-ci or yast-journal-github-ci.

    The jobs are not ready to fully replace the Travis integration, but they work and I my plan is to continue with this project later.


    TODO?


    There are still many thing to solve:

    • Coveralls - pass the Git data (branch name, etc.) from Jenkis, set the  COVERALLS_REPO_TOKEN variable, make sure it's not logged in the console to avoid compromising the value
    • Find a way how to define the scripts started in Jenkins. We need to replace the .travis.yml files with something equivalent and share the common parts effectively, very likely as a shared Rake task.
    • The current Jenkins jobs use active Git polling, we should switch that to use the GitHub web hooks 
    So stay tuned, I'll post updates on this topic...

    Bonus Section


    During the implementation I found some other interesting possibilities:


    Collecting Code Metrics and Code Coverage


    The RubyMetrics Jenkins plugin can be used to collect Flog code metrics and RCov code coverage statistics:



    That looks nice, but the practical value is low. The code coverage can be collected by Coveralls, which can comment the changes in pull requests, and code quality can be scanned e.g. by CodeClimate which provides more details about the code and better evaluates the code quality in general. More over it offers some hint what and how to fix, not just plain numbers without any clue what's wrong with the code.

    So I decided to not use them for YaST.

    Writing Jenkins Plugins in Ruby


    I found an interesting possibility when playing with Jenkins - it's possible to write a Jenkins plugins in Ruby! There is also an example. Maybe we could simple enhance Jenkins if needed...

    Monday, February 9, 2015

    Git status in bash prompt - bash-git-prompt

    Do you use Git?


    Have you ever committed a change into a wrong branch? Have you ever started working on a feature/bug fix without pulling from remote and thus need to rebase and resolve conflicts later? Have you ever forgotten your stashed changes?

    With bash-git-prompt tool that's gone!

    The tools


    Recently I was looking for some tool which would help me to avoid the problems mentioned above.

    At first I tried sexy-bash-prompt, but I didn't like the default scheme, it was too different to the usual openSUSE bash command prompt. I tried to customize it, although the code allows some customization I could not make it look like the openSUSE default.

    Then I tried bash-git-prompt. This tool is similar to sexy-bash-prompt, but provides more details about the git status. What I really like:

    • It prints more details about the current Git status (number of commits behind/ahead of remoter, count of stashed changes,...)
    • It periodically fetches the status from remote, if there are new commits on the remote you will be noticed (the check is run every 5 minutes, but it's configurable and can be completely disabled)
    • Displays the exit status of the last command, if a command fails you'll see a red X mard and the exit status number. So a failure is more visible on the terminal.
    I really recommend to give it a try if you use Git from command line, it can save you same headache...

    Installation


    Installation is really easy, just run

    cd ~
    git clone https://github.com/magicmonty/bash-git-prompt.git .bash-git-prompt
    

    If you want to update it later just run "git pull" in that directory.


    openSUSE theme


    Again the default style is too different, but it turned out that the color and the style can easily changed and bash-git-prompt already provides several styles out of box.

    So I decided to create a new style which would mimic the default openSUSE bash prompt as close as possible so you would not notice that you are using bash-git-prompt if you are outside a Git repository.

    To use bash-git-prompt with the openSUSE theme simply add this to your ~/.bashrc file:

    GIT_PROMPT_THEME=Single_line_openSUSE
    source ~/.bash-git-prompt/gitprompt.sh

    The next time you start a new shell session bash-git-prompt will be automatically loaded.

    Except the exit status at the beginning of the line it looks like the usual openSUSE bash prompt.

    Let's see how it can help with Git:





    Note: If you do not like the exit status indicator at the beginning of the line then use Single_line_NoExitState_openSUSE theme instead.

    Help


    You can run git_prompt_help to see what the used symbols mean:

     There are also some examples displayed by git_prompt_examples command:

    And if you want to change the colors used in the style you can use git_prompt_color_samples to see all colors available (note: this depends on the terminal configuration, the colors might not be the same in a different terminal):

    Note for Midnight Commander Users


    I noticed that bash-git-prompt does not work correctly when you use Midnight Commander ("mc"). The problem is that it overwrites the PROMPT_COMMAND shell variable (see more details at

    My workaround it to define an alias in ~/.alias file:

    alias gp="source ~/.bash-git-prompt/gitprompt.sh"
    

    and run "gp" whenever you want to use the bash-git-prompt functionality in mc subshell.

    (The ticket above contains a patch for mc, but you would need to recompile it from sources and maintain it yourselves, i.e. keep it up to date if a security fix is released...)