MantisBT - Doomseeker
View Issue Details
0003595Doomseeker[All Projects] Documentationpublic2019-01-06 07:252019-07-30 10:13
WubTheCaptain 
Zalewa 
normalfeaturealways
closedfixed 
1.2 
1.31.3 
0003595: Contributor documentation is not yet available
People will not likely find their way from the source distribution how to contribute to Doomseeker & Wadseeker.

I propose adding some text to README or creating a CONTRIBUTING file with this information, and more.
No tags attached.
related to 0003237closed WubTheCaptain Non-free files and copyright issues in source archive 
related to 0003533acknowledged Zalewa Replace homebrew unit testing engine with Qt Test 
related to 0003514closed Zalewa Drop support for compiling with Qt4 (in favor of Qt5+) 
parent of 0003591closed Pol M Programming style (for formatting tools like clang-format or astyle) is undocumented 
child of 0003594confirmed WubTheCaptain Documentation sprint #1: Undocumented support & contributing READMEs 
patch 0001-Add-a-README-file-for-developers.patch (6,308) 2019-06-23 02:22
https://zandronum.com/tracker/file_download.php?file_id=2491&type=bug
patch 0002-README-dev-Add-linebreaks-etc-to-hg-clone-line.patch (1,163) 2019-06-23 08:20
https://zandronum.com/tracker/file_download.php?file_id=2492&type=bug
patch 0003-README-dev-Remove-section-on-unit-tests.patch (1,052) 2019-06-23 08:20
https://zandronum.com/tracker/file_download.php?file_id=2493&type=bug
Issue History
2019-01-06 07:25WubTheCaptainNew Issue
2019-01-06 07:25WubTheCaptainNote Added: 0020304
2019-01-06 07:26WubTheCaptainRelationship addedchild of 0003594
2019-01-06 07:26WubTheCaptainAssigned To => WubTheCaptain
2019-01-06 07:26WubTheCaptainStatusnew => acknowledged
2019-01-06 07:26WubTheCaptainRelationship addedchild of 0003591
2019-01-06 07:27WubTheCaptainRelationship replacedparent of 0003591
2019-01-06 07:29WubTheCaptainStatusacknowledged => confirmed
2019-01-06 07:29WubTheCaptainTarget Version => 1.3
2019-01-16 00:06Pol MNote Added: 0020311
2019-02-05 18:16Pol MNote Added: 0020336
2019-02-05 18:16Pol MNote Deleted: 0020336
2019-06-22 22:18WubTheCaptainStatusconfirmed => assigned
2019-06-23 02:22WubTheCaptainFile Added: 0001-Add-a-README-file-for-developers.patch
2019-06-23 02:22WubTheCaptainNote Added: 0020809
2019-06-23 02:22WubTheCaptainStatusassigned => needs review
2019-06-23 02:29WubTheCaptainNote Added: 0020810
2019-06-23 02:29WubTheCaptainNote Edited: 0020810bug_revision_view_page.php?bugnote_id=20810#r12678
2019-06-23 02:29WubTheCaptainNote Edited: 0020810bug_revision_view_page.php?bugnote_id=20810#r12679
2019-06-23 02:33WubTheCaptainRelationship addedrelated to 0003237
2019-06-23 02:33WubTheCaptainRelationship addedrelated to 0003533
2019-06-23 02:36WubTheCaptainRelationship addedrelated to 0003514
2019-06-23 07:08ZalewaNote Added: 0020812
2019-06-23 07:09ZalewaNote Edited: 0020812bug_revision_view_page.php?bugnote_id=20812#r12681
2019-06-23 08:12WubTheCaptainStatusneeds review => assigned
2019-06-23 08:20WubTheCaptainFile Added: 0002-README-dev-Add-linebreaks-etc-to-hg-clone-line.patch
2019-06-23 08:20WubTheCaptainFile Added: 0003-README-dev-Remove-section-on-unit-tests.patch
2019-06-23 08:22WubTheCaptainNote Added: 0020813
2019-06-23 08:22WubTheCaptainStatusassigned => needs review
2019-06-23 08:28WubTheCaptainAssigned ToWubTheCaptain => Zalewa
2019-06-23 09:34ZalewaNote Added: 0020814
2019-06-23 09:40WubTheCaptainNote Added: 0020815
2019-06-23 09:40WubTheCaptainStatusneeds review => resolved
2019-06-23 09:40WubTheCaptainFixed in Version => 1.3
2019-06-23 09:40WubTheCaptainResolutionopen => fixed
2019-06-23 09:41WubTheCaptainNote Edited: 0020815bug_revision_view_page.php?bugnote_id=20815#r12683
2019-06-23 09:42WubTheCaptainNote Added: 0020816
2019-07-30 10:13WubTheCaptainStatusresolved => closed

Notes
(0020304)
WubTheCaptain   
2019-01-06 07:25   
Probably a link to our issue tracker, at least.
(0020311)
Pol M   
2019-01-16 00:06   
In ticket 3444 Zalewa makes some great points that should be included ^-^
(0020809)
WubTheCaptain   
2019-06-23 02:22   
Patch by me, attached.
(0020810)
WubTheCaptain   
2019-06-23 02:29   
Quote
Patch by me, attached.

Spoilers for references included:
  • Russian Overkill
  • Doom II maps, monster names, etc.
  • Push

This patch makes mentions to things which other tickets should consider with implementation. I'll try to find their relationships.

(0020812)
Zalewa   
2019-06-23 07:08   
(edited on: 2019-06-23 07:09)
It's straight to the point, just the way I like it.

Two remarks from me:

1. The .md format should maintain usability in the plain-text format as much as possible. This is achieved here, however I'd still like to nitpick about the `hg clone` line. Personally I prefer when command lines stand out in a way that makes them easy to copy and paste, especially if the command is short and fits within the column limit.


+A typical way to get started is to clone the Mercurial repository, using a
+Mercurial client from command line.
+
+ `hg clonehttps://bitbucket.org/Doomseeker/doomseeker [^]`.
+
+Refer to the manual of your client for information on interfacing
+with Mercurial.


2. The unit testing engine is not entirely useless. Yes, it's crude and doesn't automagically translate #define macros to test cases and fixtures, but it does its job if you know how to use it. Its pro point is that it's straight-forward. Everything to know about it is in the code and it doesn't need any obscure rituals to use. It's partially why I've been delaying its replacement for so long.

(0020813)
WubTheCaptain   
2019-06-23 08:22   
The first one is a fair point, although with CommonMark your exact example wouldn't do what you intended: the backticks would be visible. I addressed this in patch 0002, attached.

As for your second point, I've decided to remove the section on unit tests (for now).
(0020814)
Zalewa   
2019-06-23 09:34   
Merged the patches as-is:

1.https://bitbucket.org/Doomseeker/doomseeker/commits/44341d508b961e43c7d0fca1ffb21d5158ed1281 [^]
2.https://bitbucket.org/Doomseeker/doomseeker/commits/c9b9dcee3b4db3a9b5f353ba47349f15f9e51211 [^]
3.https://bitbucket.org/Doomseeker/doomseeker/commits/21392ebbfa73a797f61a01d0cd91569d5f53434f [^]

The end result is:https://bitbucket.org/Doomseeker/doomseeker/src/default/README-dev.md [^]

Looks good to me. Resolve?
(0020815)
WubTheCaptain   
2019-06-23 09:40   
(edited on: 2019-06-23 09:41)
I have personally used commonmark.js dingus as a reference for rendering, and thus don't really care for rendering issues which may be apparent on Bitbucket. (Maybe Bitbucket will improve or switch their renderer in the future.)

(0020816)
WubTheCaptain   
2019-06-23 09:42   
We'll probably mention this in the changelog later.