Skip to content

Commit 4b151fb

Browse files
jgmjgm
committed
Improved CONTRIBUTING.md.
1 parent 5c03275 commit 4b151fb

File tree

1 file changed

+108
-20
lines changed

1 file changed

+108
-20
lines changed

‎CONTRIBUTING.md

+108-20
Original file line numberDiff line numberDiff line change
@@ -23,47 +23,54 @@ including
2323
* the output you expected instead
2424

2525
A small test case (just a few lines) is ideal. If your input is large,
26-
spend some time trying to whittle it down to the minimum necessary to
27-
illustrate the problem.
26+
try to whittle it down to the minimum necessary to illustrate the problem.
2827

2928
Have an idea for a new feature?
3029
-------------------------------
3130

32-
Lay out the rationale for the feature you're requesting. Why would this
33-
feature be useful? Consider also any possible drawbacks, including breaking
34-
old documents.
31+
First, search [pandoc-discuss] and the issue tracker (both open and closed
32+
issues) to make sure that the idea has not been discussed before.
33+
34+
Explain the rationale for the feature you're requesting. Why would this
35+
feature be useful? Consider also any possible drawbacks, including backwards
36+
compatibility, new library dependencies, and performance issues.
3537

3638
It is best to discuss a potential new feature on [pandoc-discuss]
3739
before opening an issue.
3840

3941
Patches and pull requests
4042
-------------------------
4143

42-
Patches and pull requests are welcome. Please follow these guidelines:
44+
Patches and pull requests are welcome. Before you put time into a nontrivial
45+
patch, it is a good idea to discuss it on [pandoc-discuss], especially if it is
46+
for a new feature (rather than fixing a bug).
47+
48+
Please follow these guidelines:
4349

44-
1. Each patch should make a single logical change (fix a bug, add
50+
1. Each patch (commit) should make a single logical change (fix a bug, add
4551
a feature, clean up some code, add documentation). Everything
4652
related to that change should be included (including tests and
4753
documentation), and nothing unrelated should be included.
4854

49-
2. Follow the stylistic conventions you find in the existing
50-
panadoc code. Use spaces, not tabs, and wrap code to 80 columns.
55+
2. The first line of the commit message should be a short description
56+
of the whole commit (ideally <= 50 characters). Then there should
57+
be a blank line, followed by a more detailed description of the
58+
change.
59+
60+
3. Follow the stylistic conventions you find in the existing
61+
pandoc code. Use spaces, not tabs, and wrap code to 80 columns.
5162
Always include type signatures for top-level functions.
5263

53-
3. Your code should compile without warnings (`-Wall` clean).
64+
4. Your code should compile without warnings (`-Wall` clean).
5465

55-
4. Run the tests to make sure your code does not introduce new bugs.
56-
(See below under [Tests](#tests).)
66+
5. Run the tests to make sure your code does not introduce new bugs.
67+
(See below under [Tests](#tests).) All tests should pass.
5768

58-
5. It is a good idea to add test cases for the bug you are fixing. (See below
59-
under [Tests](#tests).) If you are adding a new writer or reader,
69+
6. It is a good idea to add test cases for the bug you are fixing. (See
70+
below under [Tests](#tests).) If you are adding a new writer or reader,
6071
you must include tests.
6172

62-
6. If you are adding a new feature, include updates to the README.
63-
64-
7. Before you put time into a nontrivial patch, it is a good idea to
65-
discuss it on [pandoc-discuss], especially if it is for a new feature
66-
(rather than fixing a bug).
73+
7. If you are adding a new feature, include updates to the README.
6774

6875
8. All code must be released under the general license governing pandoc
6976
(GPL v2).
@@ -82,9 +89,90 @@ Tests can be run as follows:
8289

8390
The test program is `tests/test-pandoc.hs`.
8491

92+
Benchmarks can be enabled by passing the `--enable-benchmarks` flag
93+
to `cabal configure`, and run using `cabal bench`.
94+
95+
The code
96+
--------
97+
98+
Pandoc has a publicly accessible git repository on
99+
github: <http://github.com/jgm/pandoc>. To get a local copy of the source:
100+
101+
git clone git://github.com/jgm/pandoc.git
102+
103+
Note: after cloning the repository (and in the future after pulling from it),
104+
you should do
105+
106+
git submodule update --init
107+
108+
to pull in changes to the templates (`data/templates/`). You can automate this
109+
by creating a file `.git/hooks/post-merge` with the contents:
110+
111+
#!/bin/sh
112+
git submodule update --init
113+
114+
and making it executable:
115+
116+
chmod +x .git/hooks/post-merge
117+
118+
The source for the main pandoc program is `pandoc.hs`. The source for
119+
the pandoc library is in `src/`, the source for the tests is in
120+
`tests/`, and the source for the benchmarks is in `benchmark/`.
121+
122+
The modules `Text.Pandoc.Definition`, `Text.Pandoc.Builder`, and
123+
`Text.Pandoc.Generics` are in a separate library `pandoc-types`. The code can
124+
be found in a <http://github.com/jgm/pandoc-types>.
125+
126+
To build pandoc, you will need a working installation of the
127+
[Haskell platform].
128+
129+
The library is structured as follows:
130+
131+
- `Text.Pandoc` is a top-level module that exports what is needed
132+
by most users of the library. Any patches that add new readers
133+
or writers will need to make changes here, too.
134+
- `Text.Pandoc.Definition` (in `pandoc-types`) defines the types
135+
used for representing a pandoc document.
136+
- `Text.Pandoc.Builder` (in `pandoc-types`) provides functions for
137+
building pandoc documents programatically.
138+
- `Text.Pandoc.Generics` (in `pandoc-types`) provides functions allowing
139+
you to promote functions that operate on parts of pandoc documents
140+
to functions that operate on whole pandoc documents, walking the
141+
tree automatically.
142+
- `Text.Pandoc.Readers.*` are the readers, and `Text.Pandoc.Writers.*`
143+
are the writers.
144+
- `Text.Pandoc.Biblio` is a utility module for formatting citations
145+
using citeproc-hs.
146+
- `Text.Pandoc.Data` is used to embed data files when the `embed_data_files`
147+
cabal flag is used. It is generated from `src/Text/Pandoc/Data.hsb` using
148+
the preprocessor [hsb2hs].
149+
- `Text.Pandoc.Highlighting` contains the interface to the
150+
highlighting-kate library, which is used for code syntax highlighting.
151+
- `Text.Pandoc.ImageSize` is a utility module containing functions for
152+
calculating image sizes from the contents of image files.
153+
- `Text.Pandoc.MIME` contains functions for associating MIME types
154+
with extensions.
155+
- `Text.Pandoc.Options` defines reader and writer options.
156+
- `Text.Pandoc.PDF` contains functions for producing a PDF from a
157+
LaTeX source.
158+
- `Text.Pandoc.Parsing` contains parsing functions used in multiple readers.
159+
- `Text.Pandoc.Pretty` is a pretty-printing library specialized to
160+
the needs of pandoc.
161+
- `Text.Pandoc.SelfContained` contains functions for making an HTML
162+
file "self-contained," by importing remotely linked images, CSS,
163+
and javascript and turning them into `data:` URLs.
164+
- `Text.Pandoc.Shared` is a grab-bag of shared utility functions.
165+
- `Text.Pandoc.Slides` contains functions for splitting a markdown document
166+
into slides, using the conventions described in the README.
167+
- `Text.Pandoc.Templates` defines pandoc's templating system.
168+
- `Text.Pandoc.UTF8` contains functions for converting text to and from
169+
UTF8 bytestrings (strict and lazy).
170+
- `Text.Pandoc.UUID` contains functions for generating UUIDs.
171+
- `Text.Pandoc.XML` contains functions for formatting XML.
85172

86173
[pandoc-discuss]: http://groups.google.com/group/pandoc-discuss
87174
[issue tracker]: https://github.com/jgm/pandoc/issues
88175
[User's Guide]: http://johnmacfarlane.net/pandoc/README.html
89176
[FAQs]: http://johnmacfarlane.net/pandoc/faqs.html
90-
177+
[Haskell platform]: http://www.haskell.org/platform/
178+
[hsb2hs]: http://hackage.haskell.org/package/hsb2hs

0 commit comments

Comments
 (0)