Skip to content
This repository was archived by the owner on Dec 28, 2022. It is now read-only.

Latest commit

 

History

History
277 lines (196 loc) · 13.3 KB

CONTRIBUTING.adoc

File metadata and controls

277 lines (196 loc) · 13.3 KB

Contributing

In the spirit of free software, everyone is encouraged to help improve this project.

To contribute code, simply fork the project on GitHub, hack away and send a pull request with your proposed changes. Feel free to use the issue tracker to provide feedback or suggestions in other ways.

Project organization

The project is hosted and run using GitHub. The issue tracker is in place to report bugs, discuss improvements, show our ambitious goals and desires for the future, and encourage each other. Classification labels and versioning tags are added for clarity and the ability to search.

Labels

Labels are added to issues and pull request for clarity, in the present but also when looking back at previous issues and pull requests.

Table 1. Type labels

bug

the current implementation has a flaw that needs to be resolved

question

generic question

improvement

refinement on top of an existing feature

enhancement

new feature

duplicate

a similar (open) issue already exists

invalid

not reproducible or out of date

declined

a decision was made not to pursue
Table 2. Category labels

grammar

how the syntax is parsed into smaller elements

snippets

included snippets to reduce the amount of typing

infrastructure

infrastructure for developing, building, testing, and hosting the project

documentation

documentation of the project, inside the code, in the included documents, or at other projects

styling

element naming and how the elements render, also for the included stylesheet
Table 3. Status labels

WIP

currently a Work In Progress, not ready for a merge

ready

development is done

Development

Before diving into the code, we recommend reading the article How to Write a Syntax Highlighting Package for Atom. That article gives you the background information you need to get started with hacking on this package.

To learn more about how the grammar works and useful resources for development, see Grammar.

Retrieve the source code

The source code for this plugin is available from https://github.com/asciidoctor/atom-language-asciidoc.

Retrieve the dependencies

Use the following command to download dependencies (Season, CoffeeLint, …​):

apm install

Prepare for business

  1. Decide what you want to work on, and what should be the result

  2. Have a GitHub account

  3. Fork the project to your personal account

  4. Check out your forked project for local development using git

  5. Navigate to the directory using the command line interface

  6. Link the package using apm link -d, and start atom in dev-mode using the command atom -d .

  7. Develop (this is where the magic happens)

  8. Commit and push your code onto your forked project

  9. Make a pull request and fill in the pull request template to request for the changes to be merged into the upstream project

  10. Answer questions or make adjustments based on the discussion around the pull request

  11. Wait for the merge, wait for the next release, use it in your normal Atom install

  12. Show off to others what you have made, and feel proud for you have improved the lives of many by contributing to this package!

Quality assurance

When opening a pull request on GitHub, Travis CI will run the Atom package specs and lint using CoffeeScript files. Of course you can do so yourself, so you can ensure your code will pass the check in the pull-request.

CoffeeScript lint

This package uses CoffeeLint to ensure that the code is uniformly structured. The linter definitions are defined in the coffeelint.json.

When developing in Atom, the linter-coffeelint package exposes the linting in your editor. It does require CoffeeLint to be installed.

CoffeeLint can also be triggered from the command line:

coffeelint -f coffeelint.json grammars/asciidoc.cson spec/*-spec.coffee snippets/language-asciidoc.cson

Package specs

Tests are defined in spec/ directory, which provide snippets of text and test if the parsed result meet the expectations. Ideally all grammar features are covered in the specs (100% test coverage), with both positive and negative tests. Having these tests present will help future contributors make improvements without accidentally breaking other parts of the package.

There are multiple ways in which you can run the tests:

Testing from the command line
atom --test spec
Testing via the Command Pallet in Atom
Window: Run Package Specs
Testing using the build-package.sh script
curl -s https://raw.githubusercontent.com/atom/ci/master/build-package.sh > build-package.sh
sh build-package.sh
Testing syntax

Grammar

The grammar is defined in files contains in the directory grammars/repositories.

The file grammars/language-asciidoc.cson is generated automatically. Please don’t change this file manually.

Generate the grammar file

  • Run Atom in Dev Mode with the following command:

atom -d .

  • Open the Command Palette with press keys: Ctrl+Shift+P

  • In the Command Palette, find and choose the item named Asciidoc Grammar: Compile grammar and reload

    • Tips: write only agc for a quick access to the item.

  • The grammar file is re-generated automatically.

Live Reload

  • To automaticaly reload the grammar when a .cson file is saved:

    • In the package settings, checked: [Only on Developer Mode] Grammars live reload

    • To quickly toggle Live Reload:

      • Open the Command Palette with press keys: Ctrl+Shift+P

      • In the Command Palette, find and choose the item named Asciidoc Grammar: Toggle Live Reload

        • Tips: write only agt for a quick access to the item.

Language definition

The Atom language definitions originate from the language definitions used by TextMate. The language definition is interpreted by the first-mate JavaScript module.

A language definition supports both single-line matches using a match regular expression (regexp), and sections matches based on a begin and end regexps. The regexps are based on the Oniguruma regexp engine (also used in Ruby), as described in Regexp handling.

TextMate oriented language resources

Naming conventions

We’re trying as much as possible to adhere to the naming guidelines described in the Naming Conventions section of the TextMate language manual. Since the grammar framework was designed with computer programming languages in mind, it’s not always clear what name to select. We must find the most logical way to map to the existing names, then try to stick to it.

Here are (some of) the patterns we’re currently using:

  • markup.heading - encloses a section title

  • markup.bold - encloses strong text

  • markup.italic - encloses emphasized text

  • markup.raw - encloses monospaced text

  • markup.link - encloses a raw URL or target of a link macro

  • comment.line - encloses a line comment

  • comment.block - encloses a block comment

  • entity.name.function - encloses the macro name

  • string.unquoted - nested content (such as inside a macro or attribute value)

  • …​

Regexp handling

Atom uses the Oniguruma library for parsing regular expressions via the node-oniguruma JavaScript module. The Oniguruma documentation provides an overview of all supported elements.

Important
 Patterns are defined as JavaScript strings. That means backslashes must be escaped twice (\\\\), backslashes in character classes escaped once (\\s), and single quotes escaped once (\').

Generally it can be said that POSIX-style regex elements are preferred (e.g., \p{Blank} and \p{Word}) as they better support internationalization.

Ruby regexp information

Regex inspiration from upstream

The upstream Asciidoctor project, written in Ruby, contains all regexes to support the full Asciidoctor ecosystem. Checking out the upstream code can thus be a great source for regex inspiration. There are however a few things to keep in mind when looking at the regular expressions in Asciidoctor core (asciidoctor.rb):

  1. The regular expressions in core are written for the Ruby 1.8 regexp engine, so they are more primitive than what Oniguruma supports. Most notably, the Ruby 1.8 regexp engine doesn’t support look-behind matches (We’re going to start using the Oniguruma engine in Asciidoctor 1.6).

  2. The regular expressions in core often capture groups in order to populate the AST node, or to perform more fine-grained parsing. The grammar doesn’t need to capture a group unless that span of text is needed for highlighting.

  3. The grammar should skip matching escaped syntax. Core captures it only because the regexp engine doesn’t support look-behind matches.

Code language support

AsciiDoc offers the ability to include source code blocks, in a variety of languages. By including the language definitions of the language set for the code block, AsciiDoc is able to offer code block language highlighting. To get the most of out of this feature, development will have to keep up with languages available in Atom. You can check the available source languages available in your Atom editor, to see if some language support is missing.

Check source language support

  1. Open the Developer Tools: Ctrl+Shift+I on Linux and Windows, Cmd+Alt+i on Mac OS X.

  2. Run the query Object.keys(atom.grammars.grammarsByScopeName).sort().join('\n') in the Console.

screenshot of a code support query
Figure 1. Example language query

Compat mode not supported

This grammar implements the modern AsciiDoc syntax endorsed by Asciidoctor. It does not support the legacy AsciiDoc syntax permitted by Asciidoctor with compat mode enabled or by AsciiDoc Python. Additionally, two-line section titles are not recognized by this grammar.

The reason compat mode is not supported is two-fold.

  1. An Atom grammar is not capable of supporting different modes based on a setting within the document.

  2. Since this project is part of the Asciidoctor organization, which endorses a modern, consistent AsciiDoc syntax, this package is aimed at encouraging migration away from the legacy syntax.

Furthermore, this grammar doesn’t support the two-line section titles for both the aforementioned reasons. That style confuses the language highlighter and we consider using that style a bad practice.

We hope this grammar encourages authors to write good, clean, modern AsciiDoc. So that’s the AsciiDoc we designed this grammar to recognize.

Snippets

Snippets are defined in snippets/language-asciidoc.cson.

Package publising

We use Travis CI to publish this package.

Every merged PR is released as a new version (by default a patch).

We use the Travis CI UI to manage the publishing system via secure environment variables:

  • PUBLISH_TYPE: default patch, can be change to minor, major.

  • STOP_PUBLISH: if defined, prevent the publishing.

  • $encrypted_xxxx_key and $encrypted_xxxx_iv: defined the main key and vector to encrypt the SSH key.

  • ATOM_ACCESS_TOKEN: defined the Atom token for apm.