[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
https://invent.kde.org/websites/rkward-kde-org/commit/19f3a80e6cd516ef030a5f94201816afd953a29f
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
-{:toc}
-
-## 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
-basics:
-<http://rkward.sourceforge.net/documents/devel/plugins/pluginhelp.html>
-
-## 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