]> https://gitweb.dealii.org/ - code-gallery.git/commitdiff
Add Howto for contributions to Readme 201/head
authorJan Philipp Thiele <thiele@wias-berlin.de>
Thu, 29 Aug 2024 13:36:32 +0000 (15:36 +0200)
committerJan Philipp Thiele <thiele@wias-berlin.de>
Thu, 29 Aug 2024 13:40:22 +0000 (15:40 +0200)
README.md

index 7d2e57f5101856b1db10a984c02c3ced6f074156..f1d001512e85132b54aee824548db3817d33c7a2 100644 (file)
--- a/README.md
+++ b/README.md
@@ -26,3 +26,80 @@ compatibility with older versions of deal.II. Older version of each
 contributed code may be attained by checking out the appropriate git commit
 of the code-gallery repository.
 
+## Contributing to the gallery
+First: **We appreciate all contributions!** 
+We have tried to set the bar to entry as low as possible.
+In essence, here is all you have to do:
+
+1. Create a fork of this repository. 
+   For this, you need to have a GitHub account. 
+   Log in, then go to this repository again and click on the `Fork` symbol at the top right.
+2. This yields a copy of the code gallery repository 
+   to which you are allowed to write (a 'fork').
+   At the right side of the page, you will find its HTTPS address. 
+   Check out a copy of it to your local hard drive via
+   ```
+    git clone https://github.com/yourusername/code-gallery.git
+   ```
+   where you replace `myusername` with your GitHub user name.
+3. Go into the `code-gallery` directory that was just generated.
+   Within it, create a new directory for your project, named as you like. 
+4. Create and switch to a branch in your local git copy:
+   ```
+   git branch my-code-gallery-project
+   git checkout my-code-gallery-project
+   ```
+5. Put your source files and everything else you need to build 
+   and run the code into this directory. 
+   In addition, the following files and subdirectories need to exist:
+   * `Readme.md:` A [markdown formatted](https://daringfireball.net/projects/markdown/basics) file that provides basic overview over what this program does. You can use LaTeX-style formulas include in `$...$`, or offset via
+     ```
+     @f{align*}{
+      ...
+     @f}
+     ```
+     to explain ideas of the program.
+   * `CMakeLists.txt:` A CMake file that allows others to build your code. 
+     It must be possible to simply run it via
+     ```
+     cmake -DDEAL_II_DIR=/path/to/dealii . ; make ; make run
+     ```
+   * `doc/entry-name:` A simple text file that contains a simple, short name of the program. 
+     This will likely match the directory name, 
+     but can contain spaces and special characters (encoded in HTML, if necessary). 
+     This name will be used in the title line of the program's page, 
+     as well as in the [list of programs](https://dealii.org/developer/doxygen/deal.II/CodeGallery.html).
+   * `doc/tooltip:` A one-line description of the program that is shown when hovering over a symbol in the connection graph.
+   * `doc/build-on:` A textfile containing a list of the form
+     ```
+     step-XX step-YY gallery-NNNN gallery-MMMM
+     ```
+     where `XX` and `YY` are the numbers of existing tutorial programs that your application builds on, 
+     and `NNNN` and `MMMM` are the directory names of existing gallery applications. 
+     This information is used to build the 
+     [connection graph for tutorial and code gallery applications.](https://dealii.org/developer/doxygen/deal.II/Tutorial.html#graph)
+   * `doc/author:` A text file containing the list of authors and their email adresses in the form
+     ```
+     Jane Doe <jane@doe.org>,
+     Helga Mustermann <helga@email.de>
+     ```
+   * `doc/dependencies:` A file with a list of entries of the form
+     ```
+     DEAL_II_WITH_CXX11 DEAL_II_WITH_TRILINOS
+     ```
+     which specifies the requirements you need the underlying deal.II installation to meet for the program to run.
+     The entries are CMake variables that are set during deal.II cofiguration
+     and correspond to the items you find printed in the summary at the end of a `cmake` run when configuring deal.II
+6. Add your code gallery directory (here: `my-project-name`)   to git 
+   and upload it to your fork of the repository:
+   ```
+   git add my-project-name 
+   git push -u origin my-code-gallery-project
+   ```
+7. Go to your GitHub code-gallery page,
+   which should be named `https://github.com/myusername/code-gallery`.
+   Sign in if necessary.
+   It should allow you to create a 'pull request' for your new code gallery project.
+   Do so -- this will alert the deal.II maintainers to the fact that you want to contribute a new project,
+   and sets up a short code for the review process.
\ No newline at end of file

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.