[PATCH] D13101: Add initial LNT developer guide

[Kristof Beyls via llvm-commits]

kristof.beyls created this revision.
kristof.beyls added reviewers: cmatthews, ddunbar.
kristof.beyls added a subscriber: llvm-commits.

After not having worked on LNT for a while, it took me a little while to figure out again how to run the LNT regression tests.
This made me think that we should have an LNT developer guide, to make it easier to get started on developing LNT.
This patch is an attempt at a very initial set of guidelines for doing LNT development.

http://reviews.llvm.org/D13101

Files:
  docs/contents.rst
  docs/developer_guide.rst

Index: docs/developer_guide.rst
===================================================================
--- /dev/null
+++ docs/developer_guide.rst
@@ -0,0 +1,49 @@
+.. _developer_guide:
+
+Developer Guide
+===============
+
+This developer guide aims to get you started with developing LNT. At the
+moment, a lot of detailed info is missing, but hopefully this will get you
+started.
+
+Installation
+------------
+
+See _quickstart for setting up an installation. Use the "develop" option when
+running ~/lnt/setup.py.
+
+Running LNT's Regression Tests
+------------------------------
+
+LNT has a growing body of regression tests that makes it easier to improve LNT
+without accidentally breaking existing functionality. Just like when developing
+most other LLVM sub-projects, you should consider adding regression tests for
+every feature you add or every bug you fix. The regression tests must pass at
+all times, therefore you should run the regression tests as part of your
+development work-flow, just like you do when developing on other LLVM
+sub-projects.
+
+The LNT regression tests make use of lit and other tools like FileCheck. At
+the moment, probably the easiest way to get them installed is to compile LLVM
+and use the binaries that are generated there. Assuming you've build LLVM
+into $LLVMBUILD, you can run the regression tests using the following command::
+
+     PATH=$LLVMBUILD/bin:$PATH llvm-lit -sv ./tests
+
+If you don't like temporary files being created in your LNT source directory,
+you can run the tests in a different directory too::
+
+     mkdir ../run_lnt_tests
+     cd ../run_lnt_tests
+     PATH=$LLVMBUILD/bin:$PATH llvm-lit -sv ../lnt/tests
+
+For simple changes, adding a regression test and making sure all regression
+tests pass, is often a good enough testing approach. For some changes, the
+existing regression tests aren't good enough at the moment, and manual testing
+will be needed. For any changes that touch on the LNT database design, you'll
+need to run tests on at least sqlite and postgress database engines.  By
+default, LNT uses sqlite, and most of the regression tests still use a
+temporary sqlite database to run tests against. Therefore, at the moment,
+you'll probably need to do some manual testing on a setup with a postgress
+database if you touch database functionality.
Index: docs/contents.rst
===================================================================
--- docs/contents.rst
+++ docs/contents.rst
@@ -16,6 +16,8 @@
 
    changes
 
+   developer_guide
+
    todo
 
 Indices and tables


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D13101.35507.patch
Type: text/x-patch
Size: 2564 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20150923/a63646f4/attachment.bin>