Skip to content

Latest commit

 

History

History
113 lines (83 loc) · 4.33 KB

CONTRIBUTING.adoc

File metadata and controls

113 lines (83 loc) · 4.33 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. Status labels

WIP

currently a Work In Progress, not ready for a merge

ready

development is done

Development

Retrieve the source code

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

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 lib/*.coffee spec/*-spec.coffee menus/*.cson keymaps/*.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