Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create a contributing guide #50

Open
mojavelinux opened this issue May 30, 2016 · 1 comment
Open

Create a contributing guide #50

mojavelinux opened this issue May 30, 2016 · 1 comment

Comments

@mojavelinux
Copy link
Member

mojavelinux commented May 30, 2016

This project should have a contributing guide (named CONTRIBUTING.adoc). It should explain how to get setup for development (pulling in content from the README), how to run tests, preferred coding style and goals for the project.

We can draw generic content and messaging from other contributing guides in the ecosystem (See https://github.com/asciidoctor/atom-language-asciidoc/blob/master/CONTRIBUTING.adoc and https://github.com/asciidoctor/asciidoctor.js/blob/master/CONTRIBUTING.adoc). What should be unique about this contributing guide is a clear list of goals for the project. Here's a draft of those goals:

  • Avoid unnecessary whitespace in the generated AsciiDoc
    • Unnecessary whitespace can be a real nuisance for users.
    • If we handle whitespace well, it's a chance to stand out against pandoc.
    • Tests should verify whitespace accuracy).
  • The code should not generate any Ruby warnings
  • Follow contribution workflow
    • Every change should be submitted as a pull request (and ideally associated with an issue)
    • Unless it's a very trivial change, pull requests should remain open for ~24 hours to provide a chance for comment and review
    • Pull requests should get a thumbs up from at least one other person in the project. Don't hesitate to mention other members in a comment to prod them.
    • If you want to avoid a merge commit, you can use the "squash and merge" feature 0of the merge button
    • Each change should have one or more tests that can verify it.
  • We should generate clean, consistent AsciiDoc, following the recommendations in the Asciidoctor User Manual. (see http://discuss.asciidoctor.org/Joining-the-Docbookrx-project-tp4695p4709.html)

The document doesn't have to be perfect to start. What's most important is that we get it started.

@mojavelinux
Copy link
Member Author

The following section from the Jekyll AsciiDoc plugin describes the coding style I'd like to adopt for this project:

https://github.com/asciidoctor/jekyll-asciidoc#coding-style

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant