Commit fb057014 authored by Nikita Melnichenko's avatar Nikita Melnichenko

imported wiki source files as is from Phabricator

The markup is not Markdown yet, however we use .md files to make use
of GitLab editing features with previews.
parent 2ce78906
A twin panel file manager. Written in C++11 with Qt5 and KF5.
= Useful links =
== General ==
* [[http://krusader.org/ | Project homepage]]
* [[http://download.kde.org/stable/krusader/ | Release downloads]]
* [[http://groups.google.com/group/krusader-users | User mailing-list]] (mainly for user questions)
* [[https://forum.kde.org/viewforum.php?f=225 | Forum]] (same purpose as user mailing list)
* [[https://bugs.kde.org/component-report.cgi?product=krusader | Bugzilla]] (for bug reports or wishes)
* [[https://www.kde.org/applications/utilities/krusader/ | Krusader introduction on kde.org]]
* [[https://store.kde.org/browse/cat/370/ord/top/ | Extensions]]
== Development ==
=== Krusader ===
* [[http://groups.google.com/group/krusader-devel | Developer mailing-list]] (for discussions, questions, etc.)
* Repositories
* Source code
* Read-only: `git://anongit.kde.org/krusader`
* Developer access: `git@git.kde.org:krusader.git`
* [[https://cgit.kde.org/krusader.git | Web-based browser]]
* [[https://github.com/KDE/krusader | GitHub mirror]] (read-only, no pull requests accepted)
* Website
* Read-only: `git://anongit.kde.org/websites/krusader-org.git`
* Developer access: `git@git.kde.org:websites/krusader-org`
* [[https://cgit.kde.org/websites/krusader-org.git | Web-based browser]]
* [[https://phabricator.kde.org/project/view/79/ | Phabricator project]] (reviews, outstanding tasks and more)
* [[https://build.kde.org/job/Extragear%20krusader%20kf5-qt5%20SUSEQt5.9/ | Jenkins]] (automatic build server, supports an RSS feed for the build status of `origin/master`)
* [[http://ebn.kde.org/krazy/reports/extragear/utils/krusader/index.html | Krazy]] (static code analysis service)
* [[https://techbase.kde.org/Policies/Frameworks_Coding_Style | Coding Style]] (KDE Frameworks coding style is preferred for Krusader project)
* [[ ./release-howto | Release Howto ]]
=== KDE ===
* KDE developer mailing-list: https://mail.kde.org/mailman/listinfo/kde-devel
* KDE system release list: https://mail.kde.org/mailman/listinfo/kde-announce
* KDE applications release list: https://mail.kde.org/mailman/listinfo/kde-announce-apps
* IRC-channel: chat.freenode.net/kde-devel (good place for quick questions regarding everything KDE related)
* Phabricator user guide, including how to submit patches: https://community.kde.org/Infrastructure/Phabricator
* Git hooks for Bugzilla: https://community.kde.org/Infrastructure/Git/Hooks#Keywords
* KIO API: https://api.kde.org/frameworks/kio/html/index.html . KIO is KDE's library for all file related operations (local and remote). Krusader does heavily depend on it.
* Porting notes, from KDE4 to KF5 (hopefully not important anymore): https://community.kde.org/Frameworks/Porting_Notes
==== Misc ====
* Recommended IDEs
** KDevelop: http://kdevelop.org
** Qt Creator: https://www.qt.io/ide/
* [[https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html | Freedesktop icon names]] (official standard icon names, try to use these instead of names only included in Breeze to be more independent from the icon theme used)
* [[https://community.kde.org/Plasma/DeveloperGuide#Icon_Viewer:_Cuttlefish | Cuttlefish]] (a useful icon browser for KDE)
* Qt's new signal/slot syntax: https://wiki.qt.io/New_Signal_Slot_Syntax
= FAQs =
==== I want to contribute. How to submit my first patch? ====
Great!
# Get a [[https://community.kde.org/Infrastructure#Identity_Accounts | KDE identity account]]
# Create a new Diff:
* https://phabricator.kde.org/differential/diff/create/ , with `krusader` as repository
* or: (**preferred**) use `arc` (see https://community.kde.org/Infrastructure/Phabricator#Using_Arcanist)
# Wait for somebody to review and accept your diff.
==== My patch has been accepted, what now? ====
See [[https://community.kde.org/Infrastructure/Phabricator#Workflow | workflow documentation]], for your first patches you will usually have to ask your reviewers to land them.
==== I want to fix a bug but there is no bug report for it yet. Do I need to file one? ====
No, not if you are certain that it really is a bug. Feel free to just submit a review.
==== I am unsure about the right approach to solve an issue, what is the best place to discuss? ====
Ask us on the [[ http://groups.google.com/group/krusader-devel | developer mailing list ]].
==== I want to know when a Krusader bug report is created (or changed) ====
To know when a Krusader bug report is created (or when an existing bug report is changed):
* You must have an account in bugs.kde.org, then you can go to «//https://bugs.kde.org > Preferences > Email preferences//» and on the "User Watching" section you can add: krusader-bugs-null@kde.org
= Commit/Patch guidelines =
Familiarize yourself with commit message style by reading several commit messages in the repository. Notice that for simple changes we use single commits and for multiple related changes we use branches and merge them into master with a descriptive merge commit message.
If your commit/patch fixes a bug reported on bugs.kde.org, use both the `FIXED:` keyword with the bug number in square brackets and bug title, and 'BUG:' keyword that triggers the Git hook to close the bug. Refer to an example below.
Your change must be reviewed and approved before you can push it to master branch. We currently use Phabricator platform for code reviews.
Your commit (or branch merge if your change is a series of commits) must contain the code review link. It's recommended to place it on the last line and separate it from summary with an empty line. For example:
> One-line commit title
>
> Description of the change. The change description
> continues.
>
> FIXED: [ 123456 ] Bug title in case you fixed a bug
> BUG: 123456
>
> Differential Revision: https://phabricator.kde.org/D12345
Once you push the commit to the repository, it will be automatically discovered by the Phabricator and it will close your code review (aka Differential) and put references to your commits.
If your changes are important enough to be included in the ChangeLog, please add a line to the commit message (summary text for the Differential on Phabricator for patches) beginning with one of these keywords {`FIXED:`, `ADDED:`, `CHANGED:`, `REMOVED:`} and a description. For example:
> CHANGED: When the big red button is pressed, foo is activated and not bar anymore
This line should not be the title of the commit message/differential. Check git history and ChangeLog for more examples of using the keywords.
= Best practice "Git vs. Phabricator" workflow =
NOTE: this is only a guideline. You can use your own workflow but be sure it is "good". If you are new to Phabricator (or Git), better do as it is described here. If you are new to Krusader development and have suggestions on how to modify it, please contact krusader-devel group.
Phabricator has a major design flaw: it alters Git commits. When a differential diff is created with `arc diff`, the last commit message is modified with potentially a huge unformatted summary text and information specific to Phabricator. These are definitely NOT good commit messages. Second, when landing the diff, all commits are squashed into one. This is against the "split changes into logical chunks"-rule for version control systems. This is default and can be changed (with the `--merge` flag). It is still annoying.
Here is are workflow for circumventing unwanted modifications:
* Create a new feature branch:
`git checkout -b feature/new-foobar-widget`
* Make your changes/commits normally you would in Git
* When done, you can upload your changes to Phabricator for review but **before** copy your feature branch for arc:
`git checkout -b feature/new-foobar-widget-arc`
* Now upload with nice information:
`arc diff --reviewers "#krusader"`
> Added new foobar widget
>
> Summary:
> Bla, Bla, Bla Mr. Freeman.
> ...
NOTE: If your base branch is not `master`, specify the base branch as well. For example,
`arc diff --reviewers "#krusader" stable`.
* In case you need to make updates based on reviewer comment or further testing, commit changes to the arc branch and run `arc diff <base-branch>`. Revision will be updated with your changes. Cherry-pick your commits to non-arc branch.
* Wait until your changes are accepted. Merge the non-arc branch with master (or simply cherry-pick and amend your commit in case of a single commit).
`git checkout master && git merge feature/new-foobar-widget`
Make sure you add code review link and keywords according to commit guidelines. The link and the keywords should go to either your single commit or branch merge commit, i.e. only appear once in history.
If your change contains multiple commits and you are still on top of master, please use `--no-ff` to keep it as a branch merge:
`git checkout master && git merge --no-ff feature/new-foobar-widget`
NOTE: Substitute `master` with your base branch if needed.
Example of branch merge commit:
> Added new foobar widget
>
> Merge branch 'feature/new-foobar-widget'
>
> Differential Revision: https://phabricator.kde.org/D1234
Done with `git pull`! The Differential diff should be automatically be closed (because of the reference).
NOTE: Don't follow this blindly. Think, test and improve if required!
== Overall release process ==
* Write a letter to krusader-devel group to claim yourself as a release manager, ask if there are any outstanding issues, code reviews, unpublished work that devs want to include into the release. Wait for a week to gather replies. Examples: [[ https://groups.google.com/d/msg/krusader-devel/TMIUqY1gyRg/_Vl7J64aBAAJ | v2.7.0 ]], [[ https://groups.google.com/d/msg/krusader-devel/a3OdfBDv4K0/b_S_uap-BgAJ | v2.7.1 ]].
* Discuss the proposed changes, set a feature freeze for the release (no new features should be included to the release later except the agreed on at this stage or bug fixes). Agree on the approximate release date. Examples: [[ https://groups.google.com/d/msg/krusader-devel/TMIUqY1gyRg/HVwioll8AAAJ | v2.7.0 ]], [[ https://groups.google.com/d/msg/krusader-devel/a3OdfBDv4K0/G2YXjGtmBwAJ | v2.7.1 ]].
* Wait for changes to be reviewed and pushed.
* Discuss and pick a release name in case of major or minor release. Bug fix releases carry the release name over.
* Create a release branch if needed (see the corresponding section below).
* Update or ask to update the documentation. Check if changes made from the previous release have been documented. Update features for major or minor release (example: [[ https://phabricator.kde.org/D12531?vs=on&id=33125 | v2.7.0 ]]).
* Propose the release date (for example, 3 weeks from now), update the docs and AppStream files. Examples: [[ https://phabricator.kde.org/D22982 | v2.7.2 ]].
* Declare the string freeze and doc freeze stage for 2 weeks and notify translators. Examples: [[https://groups.google.com/forum/#!topic/krusader-devel/Fe5bOeTbCCo | v2.7.1 ]].
* Update change logs and news in the meantime. Examples: [[ https://phabricator.kde.org/D12818?id=33973 | v2.7.0 ]], [[ https://phabricator.kde.org/D14619?id=39104 | v2.7.1 ]].
* Prepare review: version update. Examples: [[ https://phabricator.kde.org/D14621 | v2.7.1 ]].
* Prepare review: website update. Examples: [[ https://phabricator.kde.org/D14622 | v2.7.1 ]].
* On the release date: prepare and release the package (see the corresponding section below).
* Wrap up: cleanup and check a few things (see the corresponding section below).
----
== Environment ==
NOTE: this is simplified as you need to setup your developer access to be able to push later
=== First time setup ===
```
mkdir -v krusader-release-env && cd krusader-release-env
git clone git://anongit.kde.org/krusader
git clone git://anongit.kde.org/kde-dev-scripts.git
```
=== Refresh ===
```
cd krusader-release-env
cd krusader && git checkout stable && git pull ; cd ..
cd kde-dev-scripts && git pull ; cd ..
```
== Create a release branch ==
In case you're doing a minor or major release (i.e. 2.7 -> 2.8 or 2.8 -> 3.0), `stable` branch needs to be remapped.
For example, you are going to do 2.7 -> 2.8. Then
# First create a branch at the same point as `stable` to mark a past release branch. Name it `2.7`.
# Hard reset stable to `master`
# Create a commit in `master` updating the app version to `2.9.0-dev` (`stable` should keep previous master version which is `2.8.0-dev`, so no commit is needed)
# Push `master`, `2.7` and `stable` to central repo in this order.
Now you are ready for the release.
In case you're doing patch version update (i.e. 2.7.1 -> 2.7.2), no update to stable branch is needed.
== CR: Documentation and AppStream files ==
Update the following files with new release version, date, name (if applicable) and features (if applicable):
- `doc/index.docbook`
- `doc/features.docbook`
- `doc/release-overview.docbook`
- `krusader/org.kde.krusader.appdata.xml`
NOTE: Must be pushed before doc freeze email.
== CR: ChangeLog and NEWS update ==
Update the following files accordingly:
- `Changelog`
- `NEWS`
- `doc-extras/ChangeLog`
Search in git log for changelog messages and add them to the `ChangeLog` file:
```
cd krusader
LAST_VERSION="vX.Y.Z"
git log $LAST_VERSION.. | grep 'FIXED:\|ADDED:\|UPDATED:\|CHANGED:\|REMOVED:' | sort
```
Add changes from bugzilla bug reports and code reviews manually if necessary.
== CR: Version bump ==
Update the following files with new release version, date, name (if applicable):
- `CMakeLists.txt`
- `README`
NOTE: Verify that the version is building without warnings for both Debug and Release targets. Verify it's running correctly and you don't see any obvious problems. Do this ahead of time to be able to fix problems early!
== CR: Website update ==
Update the following pages:
- `index.html`
- `get-krusader/release-archive/index.html`
- `get-krusader/index.html`
- `release/{VERSION}/changelog.txt`
- `release/{VERSION}/release_notes.txt`
Copy release notes and changelog from NEWS and ChangeLog accordingly.
== On the release date ==
=== Verify the branch ===
Starting from version 2.7.1 we release only from the `stable` branch.
```
cd krusader && git checkout stable && git pull
```
Verify that ChangeLog and NEWS update is pushed or push it.
=== Commit and push version updates ===
Apply version bump commit and tag it:
```
VERSION=`cat CMakeLists.txt | grep 'set(VERSION' | awk -F '"' '{print $2; }'`
git tag -a v${VERSION} -m "Tagging krusader-${VERSION}"
```
Don't push it right away! First edit `CMakeLists.txt` to change version to development version (for example, for v2.7.1 release put `2.7.2-dev` there). Commit. Check everything is good:
```
git log
```
Now push with tags:
```
git push --follow-tags
```
This way ensures there are no commits in between version bumps.
=== Create tarball ===
Update `kde-dev-scripts/createtarball/config.ini` with
```
gitTag = vX.Y.Z
version = X.Y.Z
```
and do
```
cd ../kde-dev-scripts/createtarball/
./create_tarball_kf5.rb -n -a krusader
mv -vi krusader-$VERSION ../..
mv -vi krusader-$VERSION.tar.xz ../..
cd ../../
```
=== Test the package ===
NOTE: corrupted translated documentation can break compiling, do this!
```
mkdir -v build-${VERSION} && cd build-${VERSION} && cmake -DCMAKE_INSTALL_PREFIX=../install-${VERSION} -DQT_PLUGIN_INSTALL_DIR=../install-${VERSION} ../krusader-${VERSION} && make -j 3 && make install ; cd ..
./build-${VERSION}/krusader/krusader
```
Go to `Help -> About Krusader` and verify the version.
=== Upload the package to a KDE server ===
```
curl -T krusader-${VERSION}.tar.xz ftp://upload.kde.org/incoming/
```
=== Create a Sysadmin Request ===
Create a new Sysadmin Request asking to publish the package.
```
sha256sum krusader-${VERSION}.tar.xz
```
Example task: [[ https://phabricator.kde.org/T9350 | Krusader v2.7.1 release ]]
Task template:
```
Dear Sysadmin,
**Package pending for download.kde.org: Krusader**
New release for the Krusader project. The package is uploaded to ftp://upload.kde.org/incoming/
Desired destination: stable/krusader/{VERSION}
Full link: http://download.kde.org/stable/krusader/{VERSION}/krusader-{VERSION}.tar.xz
SHA256: {SHA256}
**Please add this release to the list of Krusader versions on bugs.kde.org.**
Thanks,
{YOUR_NAME}.
```
We ask them to add versions on Bugzilla since the //editcomponents// permission is needed. This permission allows to change settings for ALL projects. Therefore only sysadmins can do this and nobody of the Krusader devs.
=== Update the package checksum in the website change ===
Earlier, when you create the CR for the website change, you didn't know the hash of the package since you haven't created a package yet. Now you know it, and it's a good time to update it while you wait for response from admins.
Example: [[ https://phabricator.kde.org/D14622?vs=39108&id=39491 | v2.7.1 checksum update ]]
=== Wait for the package to propagate on KDE servers ===
Once admins upload the package, they will close the ticket. You need to wait until you see some mirrors become available and then you can distribute the package.
=== Update the Krusader website ===
Simply push your changes to krusader.org repository and they'll become available as soon as some recurrent job notices the change and publishes the update. May take from a few minutes to a few hours (sometimes recurrent job is down) - usually it's very quick. If your changes are not deployed in 2 hours, create a sysadmin ticket about it.
=== Send a letter to mailing lists ===
Once the website is updated, send a letter to the following mailing lists:
* krusader-devel@googlegroups.com
* krusader-users@googlegroups.com
* krusader-news@googlegroups.com
* kde-announce-apps@kde.org
Please get the permission to post ahead of time.
== Wrap up ==
=== Push createtarball config ===
The changes you made in `kde-dev-scripts` needs to be pushed to the master branch.
Example commit for [[ https://cgit.kde.org/kde-dev-scripts.git/commit/?id=61fced5cc064d22a0706173f85cfccf4d44a9a67 | v2.7.1 ]].
=== Check if bugzilla is updated accordingly ===
[[https://bugs.kde.org/enter_bug.cgi?product=krusader | Click here]] and check if new version is present in the list.
=== Merge your new version tag to master ===
Since `stable` contains changes not present in `master` (ChangeLog and documentation changes at least), you need to deliver them to the `master` branch. Merge your vX.Y.Z tag into the branch and resolve conflicts in places where version specified. Keep master version during the conflict resolution.
Example merge for [[https://cgit.kde.org/krusader.git/commit/?id=8d5946a150c7ef3e7c9607419dd45d7945d6463f | v2.7.1]].
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment