Skip to content

Latest commit

 

History

History
71 lines (65 loc) · 3.21 KB

CONTRIBUTING.org

File metadata and controls

71 lines (65 loc) · 3.21 KB
Raw

Contributing Guide

NOTE TO FUTURE CONTRIBUTORS: I plan to merge this package into GNU Elpa or Org source at some point.

So you will need to assign your copyright to FSF in order to get your patches accepted.

As a bonus, once you have assigned your copyright to FSF, doors open up for your future contributions to Emacs too!

Contribute to documentation

See Requirements for doc contributor.

  1. Clone this repo.
  2. Add/edit documentation to doc/ox-hugo-manual.org.
  3. Run make doc.
    • This generates the Markdown files for the ox-hugo documentation site and the .org files like README.org and CONTRIBUTING.org for GitHub.
  4. Review the changes in the generated .org and .md files.
  5. Commit only the .org files, push branch and create PR.
    • The .org → .md conversion is done by ox-hugo on Netlify.

Contribute to code

See Requirements for code contributor.

  1. Clone this repo.
  2. Add/edit the .el files, tests in test/site/content-org/, and documentation to doc/ox-hugo-manual.org.
  3. Run make md doc.
  4. Review the changes in the generated .org and .md files.
    • Ignore the changes shown in git diff related to only the randomly generated Org ID’s (like org17de7a9).
  5. Commit (don’t push your branch yet!).
    • As mentioned above, commit only the .org files for documentation.
  6. Run test: make -j1 test (you need to git commit i.e. do the above step before this step).
  7. Fix your commit(s) if the test fails.. repeat till you succeed.
  8. Push your feature branch and create PR.

Debug

If the ox-hugo exports do not work as expected, or if you get an error backtrace,

  1. Open an Issue.
  2. Describe the problem you are seeing.
  3. Provide the debug info:
    • Do M-x org-hugo-debug-info, That will copy the debug info in Markdown format to the kill ring. So do not manually do any other kill (copy/cut) operation after that!
    • Paste the Markdown contents in the GitHub issue.
      • You can still hit the Preview tab of the Issue before submitting it.

Test

ox-hugo is tested using two kinds of test suites:

  1. Export all the test Org files (includes file-based and subtree-based export tests) to Markdown and diff the exported Markdown against the committed reference versions.
  2. Run ert based tests.

Steps to run tests on your machine:

  1. Clone this repo.
  2. Ensure that pandoc (at least version *2.16.2*) is installed (more info here).
  3. Run make -j1 test. This runs all the tests from the two kinds of test suites described above.

ert tests

  • To run all ert based tests, run make ert.
  • To run only the ert tests matching a string foo, run make ert TEST_MATCH=foo.