From b5f42e690d83b30199121c907776f954571800c0 Mon Sep 17 00:00:00 2001 From: Jan Philipp Thiele Date: Thu, 29 Aug 2024 15:36:32 +0200 Subject: [PATCH] Add Howto for contributions to Readme --- README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/README.md b/README.md index 7d2e57f..f1d0015 100644 --- 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 , + Helga Mustermann + ``` + * `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 -- 2.39.5