[websites/rkward-kde-org] /: Reorganize some info, add instruction for submitting gltlab merge requests.

Thomas Friedrichsmeier null at kde.org
Fri Sep 11 11:16:04 BST 2020

Git commit 19f3a80e6cd516ef030a5f94201816afd953a29f by Thomas Friedrichsmeier.
Committed on 11/09/2020 at 10:15.
Pushed by tfry into branch 'master'.

Reorganize some info, add instruction for submitting gltlab merge requests.

M  +29   -56   Developer_Information.md
A  +55   -0    Patches.md
M  +6    -21   Translation_RKWard.md


diff --git a/Developer_Information.md b/Developer_Information.md
index 9959070..b08727e 100644
--- a/Developer_Information.md
+++ b/Developer_Information.md
@@ -2,67 +2,48 @@
 layout: page
-# Developer information
+# Developer resources
+You're looking to contribute, but don't know where to start? Here are some first pointers. As the very first pointer, however: Never shy away from [contacting](Contact.html) us! 
-This page has information on what you can do to help, and where to get started. Contents of this page:
-* Table of contents
-## Important starting points for all developers
-  - [RKWard Source Repository](RKWard_Source_Repository.html): For
-    developers it is highly useful to always keep track of the current
-    state of development, not only when offical versions are released.
+## Tracking bugs, tasks and feature suggestions:
+  - Submitting or browsing [Bugs and Feature Requests](Bugs.html)
   - [Open Tasks](Open_Tasks.html)
   - [Feature Plan](Feature_Plan.html)
-  - [Release Schedule](Release_Schedule.html)
-## Plugin developers
+## Important starting points for all contributors
+  - [RKWard Source Repository](RKWard_Source_Repository.html): For contributions of all kinds (code, documentation, translations, plugins) it is highly useful to always keep track of the current
+    state of development, not only when offical versions are released.
+  - [Submitting Patches](Patches.html)
+  - [Release Schedule](Release_Schedule.html)
-  - Basic documentation on writing plugins: [HTML for online
-    browsing](http://api.kde.org/doc/rkwardplugins)
-  - [Development Status of
-    Plugins](Development_Status_of_Plugins.html)
-  - [Plugins under planning](Plugins_under_planning.html)
-  - [Automated Plugin Testing](Automated_Plugin_Testing.html)
+## Documentation for documentation writers
+  - [The sources for this website](https://invent.kde.org/websites/rkward-kde-org)
+  - Info on the documentation format used in RKWard's internal documentation (the "Welcome"-pages but also Help pages for individual plugins): <https://api.kde.org/doc/rkwardplugins/pluginhelp.html>
 ## Translators
   - [Getting started with translating RKWard](Translation_RKWard.html)
-## Documentation Writers
-### Enhancing this Website
-  - Update, extend, and improve this website:
-    1. Get a [KDE identity account](https://identity.kde.org)
-    2. Go to [the RKWard website repository](https://invent.kde.org/websites/rkward-kde-org) and click "Fork"
-    3. You can edit the pages in your fork using the online editor (or the regular git workflow)
-    4. When done, create a merge request for the main repository
-### Documentation inside RKWard
-This chapter in the documentation on writing plugins provides some
-## Marketing
-  - [News Coverage](News_Coverage.html)
+## Developing plugins aka "Statistics Dialogs"
+  - Hands-on tutorial and reference on writing plugins: [HTML for online browsing](https://api.kde.org/doc/rkwardplugins)
+  - [Automated Plugin Testing](Automated_Plugin_Testing.html)
 ## C++-coders
+  - The appendix to our article in the Journal of Statistical Software discusses several aspects of the techical design, and is still mostly relevant: ([Abstract](http://www.jstatsoft.org/v49/i09), [PDF](http://www.jstatsoft.org/v49/i09/paper)).
+  - [Online API documentation](https://api.kde.org/playground-api/edu-apidocs/rkward/html/index.html)
-  - [Online API documentation](http://api.kde.org/playground-api/edu-apidocs/rkward/html/index.html)
-<!-- end list -->
+## Further resources
-  - The appendix to our article in the Journal of Statistical Software discusses several aspects of the techical design, and is still mostly relevant: ([Abstract](http://www.jstatsoft.org/v49/i09), [PDF](http://www.jstatsoft.org/v49/i09/paper)).
+### Mailing list archives
+Has something been discussed, before? Check the mailing list archives:
-## Resources
+  - <https://mail.kde.org/pipermail/rkward-devel/> (RKWard-Devel)
+  - <https://mail.kde.org/pipermail/rkward-users/> (RKWard-Users)
+  - <https://mail.kde.org/pipermail/rkward-tracker/> (RKWard-Tracker)
-The main bug tracker / feature request tracker is here, and if you want
-to report issues in RKWard, please use these:
+### Outdated pages
+Really, you should not be reading those, except when thinking about how to replace these:
+  - [Development Status of Plugins](Development_Status_of_Plugins.html)
+  - [Plugins under planning](Plugins_under_planning.html)
 ### External trackers
@@ -72,13 +53,5 @@ issues reported there concern RKWard in general. Therefore it makes
 sense to a least check these once in a while:
   - Ubuntu: <https://bugs.launchpad.net/ubuntu/+source/rkward>
-  - Debian:
-    <http://bugs.debian.org/cgi-bin/pkgreport.cgi?package=rkward>
-  - Fedora:
-    <https://bugzilla.redhat.com/buglist.cgi?component=rkward&product=Fedora>
-### Friendly mailing list archive
-  - <http://www.mail-archive.com/rkward-devel@lists.sourceforge.net/index.html>
-    is much easier to use than the "official" list archive (for
-    rkward-devel, only, at this time).
+  - Debian: <http://bugs.debian.org/cgi-bin/pkgreport.cgi?package=rkward>
+  - Fedora: <https://bugzilla.redhat.com/buglist.cgi?component=rkward&product=Fedora>
diff --git a/Patches.md b/Patches.md
new file mode 100644
index 0000000..80eb8c5
--- /dev/null
+++ b/Patches.md
@@ -0,0 +1,55 @@
+layout: page
+# Contributing source and documentation patches
+You have found a problem **and** a way to fix it (i.e. "a patch")? Then this page will show you how to contribute your patch.
+## Contributing for the impatient
+You're trying to help? Great! And if you don't feel like reading / following the instructions below, that's ok. If you're looking for the fastest way to contribute, then just contact us on the [mailing list](Contact.html).
+However one piece of advise: Please try to be as specific as possible. Importantly:
+  - When sending us a patch, please create it using ```git diff > mypatch.diff```.
+  - If the underlying issue is not yet reported, please take some time to describe it in detail. Follow the same guidlines as for [creating a bug report](Bugs.html).
+  - If you are unsure about parts of your patch (or you have not really tested it): That's nothing to be ashamed of, but please let us know!
+## The expert way to contributing patches: Gitlab merge requests
+As always with git, there are many way to accomplish something. If you are a git guru and want to do things differently, by all means do. If you just want a recipe to follow, here you go:
+### Initial steps
+  1. Get a [KDE identity account](https://identity.kde.org). In the following, we'll assume your account name is *USER*.
+  2. Find to the correct repository on invent.kde.org:
+     - [The main RKWard repository](https://invent.kde.org/education/rkward)
+     - [The RKWard website repository](https://invent.kde.org/websites/rkward-kde-org)
+  3. Fork the repository by clicking "Fork" on the repository web page (or the website repo, see above).
+  4. Clone the (original) repository to your local disk (assuming you haven't, yet):
+         `git clone https://invent.kde.org/education/rkward.git`
+  5. Add your fork to your local clone ("USER" is just a label, here; you can pick your KDE account name, or some other label to tell you that this is your fork):
+        `git remote add USER https://invent.kde.org/USER/rkward.git`
+### Starting a (patch and) merge request
+  6. For good measure, before you start, do a ```git checkout master; git pull``` in your clone. To make sure you're up to date with the most recent commits. In case of conflicts, ```git stash; git pull; git stash pop``` will usually save you.
+  7. Create a "feature branch" for your patch:
+        `git checkout -b MYPATCH`
+  8. Create and test your patch (it's ok, if you did this step before the previous one, as long did not commit anything, yet)
+  9. Once satisfied commmit your patch, locally (usually: ```git commit -a```; check your work with ```git status```), then
+        `git push --set-upstream USER MYPATCH`
+  10. Go to the webpage of your fork. You should see your new commit, there, along with a button to create a merge request. Do that.
+#### Updating your patch
+  11. Make sure you are on your already existing feature branch: ```git checkout MYPATCH```
+  12. Edit and test your patch, commit the result, locally
+  13. Pushing to your fork now becomes a little easier, as git already knows where to push the branch:
+         `git push`
+  14. The merge request is updated, automatically. For good measure navigate to https://invent.kde.org/education/rkward verify everything went as expected, and probably to leave a comment explaining your changes.
diff --git a/Translation_RKWard.md b/Translation_RKWard.md
index 4ba4399..b1befa1 100644
--- a/Translation_RKWard.md
+++ b/Translation_RKWard.md
@@ -6,24 +6,20 @@ layout: page
 ## General info
-The primary ressource for RKWard translations is <http://l10n.kde.org/>.
+The primary ressource for RKWard translations is <https://l10n.kde.org/>.
 A lot of documenation, and contact info for your language team is
 available, there.
 Note that the translation files are divided into the strings for the (core) application, and
-several separate catalogs for plugins and help pages. See below for some hints.
+several separate catalogs for plugins and help pages. For translating the latter, refer to <https://api.kde.org/doc/rkwardplugins/i18n.html>.
-## Translating RKWard the (core) application
-### Testing your translation
+## Testing your translation
 To test your translation, copy the .po file you created/modified to the
 "i18n"-subdirectory of your rkward sources. Then do cmake, make, make
 install as detailed in the INSTALL instructions.
-To switch between languages without changing the language for your
-entire desktop (or to use a language other than your desktop default),
-invoke rkward with
+*Use Settings->Switch Application Language* to switch between languages. On most systems you can also use environment variables to change the language of rkward, i.e:
 ```LANG=xx rkward```
@@ -34,20 +30,9 @@ and LC_ALL. E.g.
 ```LC_ALL=de_DE.utf-8 KDE_LANG=de rkward```
-## Translating RKWard plugins and help pages
-Plugins and Help Pages are translatable since RKWard version 0.6.3. See
-<http://api.kde.org/doc/rkwardplugins/i18n.html> for details.
 ## Developers: Maintainance of translations
 Synchronize translations from KDE l10n to git like this:
-1.  Clone (or update) the existing translation export repo:
-  ```git clone git://anongit.kde.org/scratch/tfry/rkward-po-export i18n/po```
-2.  Run
-  ```scripts/import_translations.py```
-(without language arg) to fetch updates
-3.  git commit & push in the export repo.
-Don't forget to announce upcoming releases, early, on
-kde-i18n-doc at kde.org .
+  - ```scripts/import_translations.py```
+  - ```scripts/export_translations.py```

More information about the rkward-tracker mailing list