How can we help you write packages?


#1

There are a lot of cool packages out there, but we want to make creating a package even easier! Answers to any of the questions below would help us determine the best use of our time.

  • What resources did you use learn how to create packages?

  • Was the documentation helpful? What was missing?

  • Was the API reference helpful? Was it helpful?

  • Did you look at any code from the open source packages for help? If so, which were the most helpful.

  • What is the most important thing we could do to help you write packages?


Package docs could do with a functional/architectural overview
Is There An Event Triggered When Tabs Are Changed / Active Editor Changes
#2
  1. I used the Create Package command, the documentation and the API reference (once I found it, it wasn’t completely obvious that it was there)
  2. The documentation was pretty helpful. What is missing is an introduction to Node architecture (since I’d never written code for Node before), how CoffeeScript changes that, and how to add Node package dependencies (season was my introduction to that).
  3. Very helpful. A comprehensive list of events and properties for each API class.
  4. No, once I found the API reference.
  5. I think #3, events and properties for each API class.

I think also that a discussion of how to write composable packages would be really helpful. For example, the message panel package

is a good example. I think that if Atom wants to not just equal the other editors available, but surpass them … it needs to encourage package authors to think of their packages not as a plugin that adds some functionality and will never need to be extended by the end user, but as a component that extends the reach of the editor that can be built upon even further by other package authors or the end user.


#3

Hi,

This blog article is excellent and all is said.

Generally speaking, the current documentation surely helps, but very painful to adapt based on those, and please note, ATOM official page even does not have API reference link. I happened to know there’s such a thing while googling.

Currently, I must say it is almost impossible to develop a package without reverse engineering other packages.

There’s some wiki project arround

However, I think it would be great we have an official community wiki like Linux world. We need it.

I also need JavaScript hello-world, or other concise example. I always convert coffee->js on coffeescript.org site.

Finally, I think ATOM team should establish the package eco where ChildProcess base is as a default manner since it’s so obvious ATOM gets heavier and heavier with this node single process. This is also well discussed in the article I linked.

The only package to use ChildProcess so far is atom-jshint.

I think it’s a good idea you offer a PackageGenerator based on ChildProcess template.

After all, I like ATOM a lot. Thanks.

PS. this is the example I never could find a solution.

I need to get an event the current buffer is switched among editors, among tabs.

How to do it? thanks.


#4

My general experience building a package has been a good one. I’ve been quite impressed with how elegantly the default packages are implemented and found it really useful to look at them for clues on how to do specific things. Since I’m working on a Git related package, the most useful packages were git-status and git-diff.

The documentation is pretty good, especially considering the young age of this project. I do think there needs to be a section that discusses the structure of Atom. I imagine this could start at the atom singleton and work down through the hierarchy, pointing out the public API methods and what they’re useful for e.g. atom.workspaceView.getActiveEditor(). This to me would be the most useful addition.

I think beginners would be helped by a tutorial on package construction that moves beyond an introduction. Something substantial which would illustrate a larger portion of the API e.g. listing open windows, finding the current window, manipulating it in some way. I did initially find myself at a bit of a loss after working through the current introductory tutorial.

Beyond that, some basic recipes would also help. For example, how to open panels, or open a tab and render custom content within it.


#5

It does have one, it just isn’t obivous …


#6

Thanks. What a magic the link is hidden :slight_smile:


#7

No offense, but it’s a bit surprising to find someone feel the current documentation is pretty good. It’s beta and thing goes and comes, but for instance, until I’ve read the article,

I did not know
There Are 4 Ways To Use Events
Searching for a way to register events in my plugins, I ended up reading a handful of different core Atom plugins that do event registration. A came across 4 distinct ways to actually register events:


This begs the obvious question: why 4 separate ways? It also begs the more subtle but subversive question: why would you ever register an event from a view?
Again, the lack of documentation means everyone is going to find their own slightly different way to register events. After a while, you end up with a really messy API. If you missed it— events have no docs. I guess based on that fact, it’s not too surprising that the above happened.

Please tell me where did you get the idea for subscribe events?


#8

In my experience it’s not unusual for beta software to have minimal or no documentation, so my comments were made in light of that.

Of course your experience might be different to mine.


#9

Resources

Both were quick and easy enough, and covered what I needed them to.

Documentation

I found it good for learning the basics, but pretty short. Some examples showing how to write a few types of commands would be useful, e.g. text manipulation, navigation/scrolling, creating a custom pane. Also cmd-. should definitely be mentioned in the keymaps guide.

API Reference

Nicely presented, but as others have largely covered, several big omissions:

  • A structural overview, ideally as a diagram or two.

  • Events. Both a list of core events, and the Event class itself. The latter is particularly important for custom editing commands, because it seems the most reliable way to get the “current” editor is off the event (event.targetView().editor), not getActiveEditor() which doesn’t return mini editors, or text entries in non-editor panes. (I’ve never seen this mentioned anywhere - am I wrong?)

  • The Editor reference is missing many useful methods. From the documentation I was convinced I had to get a buffer object (using the undocumented editor.buffer reference?) to do anything but the simplest text manipulation. Turns out many buffer methods are on editor too.

  • How to get from a view to the underlying model. I’ve found stuff squirreled away in the jquery data() store of nodes, but as it’s not documented it feels dirty. Would be nice if this was part of the API.

Finally as a hopeful Emacs convert, one thing I really miss is documentation built into the editor itself. If we were to establish some conventions (e.g., perhaps a “doc” property of a function is its documentation), a whole host of useful documentation tools could be built by anyone. Could also make it easier to spot missing documentation.

Open Source Packages

I’ve learned a lot from vim-mode, and have started snooping through Atom.app to grok some core stuff.

Most Important Thing

The reference issues above.


#10

When I was writing syntax-settings I relied extensively on the documentation and this wonderful site. Here are my thoughts:

  1. Generate package command - works wonderfully
  2. Documentation was really good. I think there is a need for some more on how to set up default settings for your package, but I found what I needed.
  3. Reference was good for my needs. Somewhat confusing at this point to find the exact hierarchy of all the classes but a great start.
  4. Not really!
  5. Events and how to subscribe to them. I could not find much at all on this and what I did find all related to Views (which I haven’t used yet). I really wanted to capture some of the events (eg. ‘save’) but everything broke as soon as I tried.

Edit: I recently noticed all the events in the TextBuffer docs. Yay!


#11

I can’t say the documentation didn’t help me, but in practice I spent more time digging in the sources of atom and open source packages than browsing the documentation.

For instance, regarding buffer markers, while the Marker class is documented, the DisplayBufferMarker class isn’t. But if you have to visually display these markers, you’ll have to rely on DisplayBufferMarker and the editor methods, so I add to dig in the find-and-replace package to understand how these methods worked (fortunately, browsing Atom.app gives access to these classes).

There’s also a lot of classes for which documentation doesn’t list the available events, I had to search all emit instances in the code to find which events a class emit.

But as previously said, this is a beta and I didn’t expected a proper documentation in the first place.

Maybe it could be good to have some kind guidelines on how structure packages classes, For atom-color-highlight I tried to follow the structure of native packages such find-and-replace or bracket-matchers to handle properly views/buffer/markers lifecycle, but I noticed that a lot of similar packages didn’t bother with that, often relying on generated markup instead of buffer markers, what is the best course of action in that case ?
Maybe the Atom team could brief us a bit on what should and shouldn’t be done when trying to works with buffer and grammar (see this topic for instance)

My 2 cents


#12

Resources

Pretty much what @oggy said.

API Reference

  • I’m new to coffeescript. In fact, Atom made me use coffeescript, and the API reference helped me a lot. So far I’m having fun poking around the API reference. But, there are things that can be improved on.
  • The API Reference is pretty sparse on descriptions and examples, but so far I get by by using console.log
  • At this point, console.log is an invaluable tool for discovering hidden features, ie. retainSelection
  • It seems that there are many ways to do things, like for instance, getting the active editor. The alternatives should be documented together.

Open Source Packages

I looked at vim-mode to help me get started. I also find block-travel interesting.

Most Importantly

There must be a way to depend on other apm packages without. I’m not sure if there is such feature, but if there is, it’s not so obvious. I also heard from someone in irc that you can depend on another apm package as long as it is in npm, which is not so ideal since npm is not specifically for atom.

This is important for me because I saw some packages that can be used in my package. In my package, I can also see some features that can be split into a different package. For instance, atomic-emacs can make good use of block-travel, and in atomic-emacs it is possible to split the “sticky selection” feature into another package.


#13

Resources:

These are the places I look for information while I’m hacking, roughly in order:

  1. The official API reference. I usually keep a tab open here while I’m working as a quick reference.
  2. Open-source packages, both the official GitHub ones and otherwise. I’ll often hunt down the implementation of a specific feature I want to emulate by trying to see how someone else already did it. It’s also a good way to track down support libraries that already exist; this is how I found out about Emissary, for example.
  3. The Javascript source in /Applications/Atom.app, especially for Editor and EditorView internals, undocumented methods, and so on. Most recently I’ve been tracing through EditorView to figure out the best way to persistently attach a CSS class to certain .line elements, for example.

I will say that the built-in “Create a package” command is excellent for bootstrapping plugins, although I was surprised that it didn’t create the package in dev/.

Documentation:

I read through the package creation tutorial when I was first getting started, but I haven’t had cause to revisit it much since then. It’s a decent introduction to the major classes in the API and the mechanics of development and publishing, but it’s not really comprehensive.

What would be interesting are a set of follow-on articles for specific topics: event broadcast and subscription, text buffer operations, plugin architecture, writing specs for Views…

API Reference:

As I mentioned, this is the first place I look when I’m hunting for the way to accomplish something specific. It’s a good start, but it is missing some key bits (@abe mentioned the missing DisplayBufferMarker class, for example).

I’ll echo some others that event documentation is probably the biggest omission: what events are broadcast when.

Open-source packages:

Yes, I’ve referred to a bunch of the open-source packages for guidance. I hunted down how to write view specs from vim-mode, I think.

The most important thing

Keep adding content to the API documentation; keep providing high-quality examples. Make sure that API stability is made clear, moving forward.

Overall, I’ve been having a lot of fun hacking on Atom, and I’m looking forward to seeing where it goes in the future. :grinning:

@ProbablyCorey: By the way, what’s the best channel for requesting additions to the API? The feedback button, topics here… ?


Where to begin with contributing?
#14

@smashwilson the packages category on this forum is the best place to post API requests, or problems you noticed with the API.


#15

This topic is now pinned. It will appear at the top of its category until it is either unpinned by a moderator, or the Clear Pin button is pressed.


#16

The biggest issue I’ve faced is not knowing what events I can subscribe to and what calls them. A lot of the time it’s trail and error.


#17

+1 on docs for events - hunting around in the inspector can suffice for now, but there’s lots of trial and error.


#18

In-house grammar documentation instead of referring to the TextMate manual, particularly with stuff where it’s unclear what Atom does or doesn’t explicitly support like recursive grammars, referencing other grammars, and so on.


#19

I would love to see a way to write packages without being forced to write it in coffee-script. I personally dislike coffee-script and believe it hinders me for performing otherwise mundane tasks. Others love it. Both oppinions is fine, and both exists - why not allow both?


#20

Both are allowed. There is some question around how well supported writing extensions in JavaScript are because of complications around extending the View class … but both are possible to my understanding.