#+TITLE: Contributing Guide
#+AUTHOR: Kaushal Modi
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.

- [[https://www.gnu.org/licenses/why-assign.html][Why assign copyright to FSF?]]
- [[https://www.gnu.org/prep/maintain/html_node/Copyright-Papers.html#Copyright-Papers][How to start this process]]

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 [[https://ox-hugo.scripter.co/doc/requirements/#doc_contributor_reqs][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 [[https://ox-hugo.scripter.co/doc/requirements/#code_contributor_reqs][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 [[https://github.com/kaushalmodi/ox-hugo/issues][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
1. Clone this repo.
2. Ensure that ~pandoc~ and ~pandoc-citeproc~ (at least version
   [[https://github.com/jgm/pandoc/releases/tag/2.9.2.1][*2.9.2.1*]]) are installed (more info
   [[https://ox-hugo.scripter.co/doc/contributing-guide/#contribute-to-code][here]]).
3. Run =make -j1 test=.
