[elpa] master 342f3dd 109/135: Improved contributing section in documentation

[Ian Dunn]

branch: master
commit 342f3dd7207ca934002f982bb8a7f5c516e8a684
Author: Ian Dunn <address@hidden>
Commit: Ian Dunn <address@hidden>

    Improved contributing section in documentation
    
    * org-edna.org (Installation and Setup): Removed compilation instructions.
      (Finder Cache): New section documenting cache setup.
      (Working with EDE): New section about EDE.
      (Compiling Edna): New section about compiling Edna.
      (Testing Edna): New section on how to test Edna.
      (Before Sending Changes): Moved out of "development"
      (Developing with Bazaar): Moved out of "development"
      (Development): Removed.
      (Changelog): Updated.
---
 org-edna.info | 322 ++++++++++++++++++++++++++++++++++++++++++----------------
 org-edna.org  | 152 ++++++++++++++++++++++++---
 2 files changed, 373 insertions(+), 101 deletions(-)

diff --git a/org-edna.info b/org-edna.info
index 33b6708..fde1e6e 100644
--- a/org-edna.info
+++ b/org-edna.info
@@ -76,6 +76,7 @@ Actions
 
 Advanced Features
 
+* Finder Cache::                 Making the finders work faster
 * Conditions::                   More than just DONE headings
 * Consideration::                Only some of them
 * Conditional Forms::            If/Then/Else
@@ -102,11 +103,16 @@ Extending Edna
 Contributing
 
 * Bugs::
-* Development::
+* Working with EDE::             And all its quirks
+* Compiling Edna::               How to compile Edna
+* Testing Edna::                 Ensuring Edna works the way we think she will
+* Before Sending Changes::       Follow these instructions before sending us 
anything
+* Developing with Bazaar::       How to use this strange VCS
 * Documentation::                Improving the documentation
 
 Changelog
 
+* 1.0beta7: 10beta7.
 * 1.0beta6: 10beta6.
 * 1.0beta5: 10beta5.
 * 1.0beta4: 10beta4.
@@ -184,13 +190,12 @@ org     9.0.5
    From Source:
 
      bzr branch https://bzr.savannah.gnu.org/r/org-edna-el/ org-edna
-     make -C org-edna compile autoloads
 
    After that, add the following to your init file (typically .emacs):
 
      ;; Only necessary if installing from source
      (add-to-list 'load-path "/full/path/to/org-edna/")
-     (load "/path/to/org-edna/org-edna-autoloads.el")
+     (require 'org-edna)
 
      ;; Always necessary
      (org-edna-load)
@@ -1056,13 +1061,39 @@ Advanced Features
 
 * Menu:
 
+* Finder Cache::                 Making the finders work faster
 * Conditions::                   More than just DONE headings
 * Consideration::                Only some of them
 * Conditional Forms::            If/Then/Else
 * Setting the Properties::       The easy way to set BLOCKER and TRIGGER
 
 
-File: org-edna.info,  Node: Conditions,  Next: Consideration,  Up: Advanced 
Features
+File: org-edna.info,  Node: Finder Cache,  Next: Conditions,  Up: Advanced 
Features
+
+Finder Cache
+============
+
+Some finders, ‘match’ in particular, can take a long time to run.
+Oftentimes, this can make it unappealing to use Edna at all, especially
+with long checklists.
+
+   The finder cache is one solution to this.  To enable it, set
+‘org-edna-finder-use-cache’ to non-nil.  This can be done through the
+customization interface, or manually with ‘setq’.
+
+   When enabled, the cache will store the results of every finder form
+for a configurable amount of time.  This timeout is controlled by
+‘org-edna-finder-cache-timeout’.  The cache is also invalidated if any
+of the results are invalid, which can happen if their target files have
+been closed.
+
+   For example, if there are several entries in a checklist that all use
+the form ‘match("daily")’ as part of their trigger, the results of that
+form will be cached.  When the next item is marked as DONE, the results
+will be searched for in cache, not recomputed.
+
+
+File: org-edna.info,  Node: Conditions,  Next: Consideration,  Prev: Finder 
Cache,  Up: Advanced Features
 
 Conditions
 ==========
@@ -1441,11 +1472,15 @@ We are all happy for any help you may provide.
 * Menu:
 
 * Bugs::
-* Development::
+* Working with EDE::             And all its quirks
+* Compiling Edna::               How to compile Edna
+* Testing Edna::                 Ensuring Edna works the way we think she will
+* Before Sending Changes::       Follow these instructions before sending us 
anything
+* Developing with Bazaar::       How to use this strange VCS
 * Documentation::                Improving the documentation
 
 
-File: org-edna.info,  Node: Bugs,  Next: Development,  Up: Contributing
+File: org-edna.info,  Node: Bugs,  Next: Working with EDE,  Up: Contributing
 
 Bugs
 ====
@@ -1459,10 +1494,111 @@ There are two ways to submit bug reports:
 caused the bug, with as much context as possible.
 
 
-File: org-edna.info,  Node: Development,  Next: Documentation,  Prev: Bugs,  
Up: Contributing
+File: org-edna.info,  Node: Working with EDE,  Next: Compiling Edna,  Prev: 
Bugs,  Up: Contributing
+
+Working with EDE
+================
+
+Our build system uses EDE. EDE can be a little finicky at times, but we
+feel the benefits, namely package dependency handling and Makefile
+generation, outweigh the costs.
+
+   One of the issues that many will likely encounter is the error
+“Corrupt file on disk”.  This is most often due to EDE not loading all
+its subprojects as needed.  If you find yourself dealing with this error
+often, place the following in your .emacs file:
+
+     ;; Target types needed for working with edna
+     (require 'ede/proj-elisp)
+     (require 'ede/proj-aux)
+     (require 'ede/proj-misc)
+
+   These are the three target types that edna uses: elisp for
+compilation and autoloads; aux for auxiliary files such as
+documentation; and misc for tests.
+
+   When creating a new file, EDE will ask if you want to add it to a
+target.  Consult with one of the edna devs for guidance, but usually
+selecting “none” and letting one of us handle it is a good way to go.
+
+
+File: org-edna.info,  Node: Compiling Edna,  Next: Testing Edna,  Prev: 
Working with EDE,  Up: Contributing
+
+Compiling Edna
+==============
+
+To compile Edna, you’ve got to have EDE create the Makefile first.  Run
+the following in your Emacs instance to generate the Makefile:
+
+     M-x ede-proj-regenerate
+
+   This will create the Makefile and point it to the correct version of
+Org.  The targets are as follows:
+
+compile
+     Compiles the code.  This should be done to verify that everything
+     will compile, as ELPA requires this.
+autoloads
+     Creates the autoloads file.  This should also run without problems,
+     so it’s a good idea to check this one as well.
+check
+     Runs the tests in ‘org-edna-tests.el’.
+
+   To run any target, call ‘make’:
+
+     make compile autoloads
+
+   The above command compiles Edna and generates the autoloads file.
+
+
+File: org-edna.info,  Node: Testing Edna,  Next: Before Sending Changes,  
Prev: Compiling Edna,  Up: Contributing
+
+Testing Edna
+============
+
+There are two ways to test Edna: the command-line and through Emacs.
+
+   The command-line version is simple, and we ask that you do any final
+testing using this method.  This is how we periodically check to verify
+that new versions of Org mode haven’t broken Edna.  It uses the
+Makefile, which is generated with EDE. See *note Compiling Edna:: for
+how to do that.  Once you have, run ‘make check’ on the command line.
+
+   Edna tests are written using ‘ERT’, the Emacs Regression Testing
+framework.  In order to use it interactively in Emacs, the following
+must be done:
+
+  1. Load ‘org-edna-tests.el’
+  2. Run ‘M-x ert-run-tests-interactively’
+  3. Select which tests to run, or just the letter “t” to run all of
+     them.
+
+   Results are printed in their own buffer.  See the ERT documentation
+for more details.
+
+
+File: org-edna.info,  Node: Before Sending Changes,  Next: Developing with 
Bazaar,  Prev: Testing Edna,  Up: Contributing
+
+Before Sending Changes
+======================
+
+There are a few rules to follow:
+
+   • Verify that any new Edna keywords follow the appropriate naming
+     conventions
+   • Any new keywords should be documented
+   • We operate on headings, not headlines
+        • Use one word in documentation to avoid confusion
+   • Make sure your changes compile
+   • Run ’make check’ to verify that your mods don’t break anything
+   • Avoid additional or altered dependencies if at all possible
+        • Exception: New versions of Org mode are allowed
+
+
+File: org-edna.info,  Node: Developing with Bazaar,  Next: Documentation,  
Prev: Before Sending Changes,  Up: Contributing
 
-Development
-===========
+Developing with Bazaar
+======================
 
 If you’re new to bazaar, we recommend using Emacs’s built-in VC package.
 It eases the overhead of dealing with a brand new VCS with a few
@@ -1478,19 +1614,8 @@ Emacs, this is C-h r m Introduction to VC RET).
    Then, use ‘org-edna-submit-bug-report’ and attach “file-name.txt”.
 We can then merge that into the main development branch.
 
-   There are a few rules to follow:
-
-   • Verify that any new Edna keywords follow the appropriate naming
-     conventions
-   • Any new keywords should be documented
-   • We operate on headings, not headlines
-        • Use one word to avoid confusion
-   • Run ’make check’ to verify that your mods don’t break anything
-   • Avoid additional or altered dependencies if at all possible
-        • Exception: New versions of Org mode are allowed
-
 
-File: org-edna.info,  Node: Documentation,  Prev: Development,  Up: 
Contributing
+File: org-edna.info,  Node: Documentation,  Prev: Developing with Bazaar,  Up: 
Contributing
 
 Documentation
 =============
@@ -1511,6 +1636,7 @@ Changelog
 
 * Menu:
 
+* 1.0beta7: 10beta7.
 * 1.0beta6: 10beta6.
 * 1.0beta5: 10beta5.
 * 1.0beta4: 10beta4.
@@ -1518,7 +1644,21 @@ Changelog
 * 1.0beta2: 10beta2.
 
 
-File: org-edna.info,  Node: 10beta6,  Next: 10beta5,  Up: Changelog
+File: org-edna.info,  Node: 10beta7,  Next: 10beta6,  Up: Changelog
+
+1.0beta7
+========
+
+Biggest change here is the cache.
+
+   • Added cache to the finders to improve performance
+
+   • Updated documentation to include EDE
+
+   • Added testing and compiling documentation
+
+
+File: org-edna.info,  Node: 10beta6,  Next: 10beta5,  Prev: 10beta7,  Up: 
Changelog
 
 1.0beta6
 ========
@@ -1610,72 +1750,78 @@ Big release here, with three new features.
 
 Tag Table:
 Node: Top225
-Node: Copying3693
-Node: Introduction4515
-Node: Installation and Setup5463
-Node: Basic Operation6256
-Node: Blockers8107
-Node: Triggers8393
-Node: Syntax8655
-Node: Basic Features9345
-Node: Finders9648
-Node: ancestors11413
-Node: children12007
-Node: descendants12417
-Node: file12939
-Node: first-child13688
-Node: ids13948
-Node: match14609
-Node: next-sibling15247
-Node: next-sibling-wrap15504
-Node: olp15818
-Node: org-file16230
-Node: parent16875
-Node: previous-sibling17073
-Node: previous-sibling-wrap17334
-Node: relatives17613
-Node: rest-of-siblings21234
-Node: rest-of-siblings-wrap21519
-Node: self21868
-Node: siblings22029
-Node: siblings-wrap22266
-Node: Actions22570
-Node: Scheduled/Deadline23312
-Node: TODO State26887
-Node: Archive27255
-Node: Chain Property27575
-Node: Clocking27858
-Node: Property28270
-Node: Priority30457
-Node: Tag31026
-Node: Effort31243
-Node: Advanced Features31632
-Node: Conditions32016
-Node: done32631
-Node: headings32795
-Node: todo-state33171
-Node: variable-set33427
-Node: has-property33856
-Node: re-search34125
-Node: Negating Conditions34485
-Node: Consideration34872
-Node: Conditional Forms36441
-Node: Setting the Properties39097
-Node: Extending Edna40181
-Node: Naming Conventions40671
-Node: Finders 141132
-Node: Actions 141494
-Node: Conditions 141953
-Node: Contributing42839
-Node: Bugs43390
-Node: Development43742
-Node: Documentation44895
-Node: Changelog45340
-Node: 10beta645548
-Node: 10beta545808
-Node: 10beta446195
-Node: 10beta346448
-Node: 10beta246887
+Node: Copying4093
+Node: Introduction4915
+Node: Installation and Setup5863
+Node: Basic Operation6587
+Node: Blockers8438
+Node: Triggers8724
+Node: Syntax8986
+Node: Basic Features9676
+Node: Finders9979
+Node: ancestors11744
+Node: children12338
+Node: descendants12748
+Node: file13270
+Node: first-child14019
+Node: ids14279
+Node: match14940
+Node: next-sibling15578
+Node: next-sibling-wrap15835
+Node: olp16149
+Node: org-file16561
+Node: parent17206
+Node: previous-sibling17404
+Node: previous-sibling-wrap17665
+Node: relatives17944
+Node: rest-of-siblings21565
+Node: rest-of-siblings-wrap21850
+Node: self22199
+Node: siblings22360
+Node: siblings-wrap22597
+Node: Actions22901
+Node: Scheduled/Deadline23643
+Node: TODO State27218
+Node: Archive27586
+Node: Chain Property27906
+Node: Clocking28189
+Node: Property28601
+Node: Priority30788
+Node: Tag31357
+Node: Effort31574
+Node: Advanced Features31963
+Node: Finder Cache32411
+Node: Conditions33450
+Node: done34086
+Node: headings34250
+Node: todo-state34626
+Node: variable-set34882
+Node: has-property35311
+Node: re-search35580
+Node: Negating Conditions35940
+Node: Consideration36327
+Node: Conditional Forms37896
+Node: Setting the Properties40552
+Node: Extending Edna41636
+Node: Naming Conventions42126
+Node: Finders 142587
+Node: Actions 142949
+Node: Conditions 143408
+Node: Contributing44294
+Node: Bugs45160
+Node: Working with EDE45517
+Node: Compiling Edna46601
+Node: Testing Edna47470
+Node: Before Sending Changes48451
+Node: Developing with Bazaar49138
+Node: Documentation49879
+Node: Changelog50335
+Node: 10beta750564
+Node: 10beta650842
+Node: 10beta551118
+Node: 10beta451505
+Node: 10beta351758
+Node: 10beta252197
 
 End Tag Table
 
diff --git a/org-edna.org b/org-edna.org
index 31240c9..6e6c35f 100644
--- a/org-edna.org
+++ b/org-edna.org
@@ -70,7 +70,6 @@ From Source:
 
 #+BEGIN_SRC shell
 bzr branch https://bzr.savannah.gnu.org/r/org-edna-el/ org-edna
-make -C org-edna compile autoloads
 #+END_SRC
 
 After that, add the following to your init file (typically .emacs):
@@ -78,7 +77,7 @@ After that, add the following to your init file (typically 
.emacs):
 #+BEGIN_SRC emacs-lisp
 ;; Only necessary if installing from source
 (add-to-list 'load-path "/full/path/to/org-edna/")
-(load "/path/to/org-edna/org-edna-autoloads.el")
+(require 'org-edna)
 
 ;; Always necessary
 (org-edna-load)
@@ -874,6 +873,30 @@ Sets the effort of all targets according to VALUE:
 :PROPERTIES:
 :CUSTOM_ID: advanced
 :END:
+** Finder Cache
+:PROPERTIES:
+:CUSTOM_ID: cache
+:DESCRIPTION: Making the finders work faster
+:END:
+
+Some finders, ~match~ in particular, can take a long time to run.  Oftentimes,
+this can make it unappealing to use Edna at all, especially with long
+checklists.
+
+The finder cache is one solution to this.  To enable it, set
+~org-edna-finder-use-cache~ to non-nil.  This can be done through the
+customization interface, or manually with ~setq~.
+
+When enabled, the cache will store the results of every finder form for a
+configurable amount of time.  This timeout is controlled by
+~org-edna-finder-cache-timeout~.  The cache is also invalidated if any of the
+results are invalid, which can happen if their target files have been closed.
+
+For example, if there are several entries in a checklist that all use the form
+~match("daily")~ as part of their trigger, the results of that form will be
+cached.  When the next item is marked as DONE, the results will be searched for
+in cache, not recomputed.
+
 ** Conditions
 :PROPERTIES:
 :CUSTOM_ID: conditions
@@ -1238,6 +1261,9 @@ git clone git://orgmode.org/org-mode.git
 #+END_SRC
 
 ** Bugs
+:PROPERTIES:
+:CUSTOM_ID: bugs
+:END:
 
 There are two ways to submit bug reports:
 
@@ -1247,7 +1273,110 @@ There are two ways to submit bug reports:
 When submitting a bug report, be sure to include the Edna form that caused the
 bug, with as much context as possible.
 
-** Development
+** Working with EDE
+:PROPERTIES:
+:CUSTOM_ID: ede
+:DESCRIPTION: And all its quirks
+:END:
+
+Our build system uses EDE.  EDE can be a little finicky at times, but we feel
+the benefits, namely package dependency handling and Makefile generation,
+outweigh the costs.
+
+One of the issues that many will likely encounter is the error "Corrupt file on
+disk".  This is most often due to EDE not loading all its subprojects as 
needed.
+If you find yourself dealing with this error often, place the following in your
+.emacs file:
+
+#+begin_src emacs-lisp
+;; Target types needed for working with edna
+(require 'ede/proj-elisp)
+(require 'ede/proj-aux)
+(require 'ede/proj-misc)
+#+end_src
+
+These are the three target types that edna uses: elisp for compilation and
+autoloads; aux for auxiliary files such as documentation; and misc for tests.
+
+When creating a new file, EDE will ask if you want to add it to a target.
+Consult with one of the edna devs for guidance, but usually selecting "none"
+and letting one of us handle it is a good way to go.
+
+** Compiling Edna
+:PROPERTIES:
+:CUSTOM_ID: compiling
+:DESCRIPTION: How to compile Edna
+:END:
+To compile Edna, you've got to have EDE create the Makefile first.  Run the
+following in your Emacs instance to generate the Makefile:
+
+#+begin_example
+M-x ede-proj-regenerate
+#+end_example
+
+This will create the Makefile and point it to the correct version of Org.  The
+targets are as follows:
+
+- compile :: Compiles the code.  This should be done to verify that everything
+             will compile, as ELPA requires this.
+- autoloads :: Creates the autoloads file.  This should also run without
+               problems, so it's a good idea to check this one as well.
+- check :: Runs the tests in ~org-edna-tests.el~.
+
+To run any target, call ~make~:
+
+#+begin_src shell
+make compile autoloads
+#+end_src
+
+The above command compiles Edna and generates the autoloads file.
+
+** Testing Edna
+:PROPERTIES:
+:CUSTOM_ID: testing
+:DESCRIPTION: Ensuring Edna works the way we think she will
+:END:
+
+There are two ways to test Edna: the command-line and through Emacs.
+
+The command-line version is simple, and we ask that you do any final testing
+using this method.  This is how we periodically check to verify that new
+versions of Org mode haven't broken Edna.  It uses the Makefile, which is
+generated with EDE.  See [[#compiling][Compiling Edna]] for how to do that.  
Once you have, run
+~make check~ on the command line.
+
+Edna tests are written using ~ERT~, the Emacs Regression Testing framework.  In
+order to use it interactively in Emacs, the following must be done:
+
+1. Load ~org-edna-tests.el~
+2. Run ~M-x ert-run-tests-interactively~
+3. Select which tests to run, or just the letter "t" to run all of them.
+
+Results are printed in their own buffer.  See the ERT documentation for more
+details.
+
+** Before Sending Changes
+:PROPERTIES:
+:CUSTOM_ID: commit_checklist
+:DESCRIPTION: Follow these instructions before sending us anything
+:END:
+
+There are a few rules to follow:
+
+- Verify that any new Edna keywords follow the appropriate naming conventions
+- Any new keywords should be documented
+- We operate on headings, not headlines
+  - Use one word in documentation to avoid confusion
+- Make sure your changes compile
+- Run 'make check' to verify that your mods don't break anything
+- Avoid additional or altered dependencies if at all possible
+  - Exception: New versions of Org mode are allowed
+
+** Developing with Bazaar
+:PROPERTIES:
+:CUSTOM_ID: bzr_dev
+:DESCRIPTION: How to use this strange VCS
+:END:
 
 If you're new to bazaar, we recommend using Emacs's built-in VC package.  It
 eases the overhead of dealing with a brand new VCS with a few standard 
commands.
@@ -1265,16 +1394,6 @@ $ bzr send -o file-name.txt
 Then, use ~org-edna-submit-bug-report~ and attach "file-name.txt".  We can then
 merge that into the main development branch.
 
-There are a few rules to follow:
-
-- Verify that any new Edna keywords follow the appropriate naming conventions
-- Any new keywords should be documented
-- We operate on headings, not headlines
-  - Use one word to avoid confusion
-- Run 'make check' to verify that your mods don't break anything
-- Avoid additional or altered dependencies if at all possible
-  - Exception: New versions of Org mode are allowed
-
 ** Documentation
 :PROPERTIES:
 :CUSTOM_ID: docs
@@ -1292,7 +1411,14 @@ making any changes:
 :DESCRIPTION: List of changes by version
 :END:
 ** 1.0beta7
+Biggest change here is the cache.
+
 - Added cache to the finders to improve performance
+
+- Updated documentation to include EDE
+
+- Added testing and compiling documentation
+
 ** 1.0beta6
 Lots of parsing fixes.