Project

General

Profile

Feature #12164

Add a HACKING document for new code contributors

Added by anonym about 1 year ago. Updated 12 months ago.

Status:
Resolved
Priority:
Normal
Assignee:
-
Category:
-
Target version:
Start date:
01/22/2017
Due date:
% Done:

100%

QA Check:
Pass
Feature Branch:
doc/HACKING
Type of work:
Contributors documentation
Blueprint:
Starter:
Affected tool:

Description

Recently I've found myself repeatedly explaining primarily Tails source tree to new prospective contributors. I think we should have a short document explaining the basics of it (which will be enough for 95% of new contributions) that tries to be self-contained instead of referring to our copious amounts of contributor docs which might scare people away. It should be possible to read in at most 20 minutes or so.

Associated revisions

Revision 70f92b7c
Added by anonym 12 months ago

Merge branch 'doc/HACKING'

Fix-committed: #12164

History

#1 Updated by anonym about 1 year ago

  • Status changed from Confirmed to In Progress
  • Assignee changed from anonym to intrigeri
  • % Done changed from 0 to 50
  • Feature Branch set to doc/HACKING

Can you double-check that I haven't done any serious mistakes? Also, feel free to fixup the hastily-written language if you feel like it, or add important bits you think are missing, and remove parts you feel don't belong. Please review'n'merge into the master branch.

#2 Updated by cbrownstein about 1 year ago

Extremely minor grammatical error at line 5 of HACKING.mdwn:

Tails by giving a brief overview OF the Tails source tree and Git branch

#3 Updated by intrigeri about 1 year ago

  • QA Check set to Ready for QA

#4 Updated by intrigeri about 1 year ago

  • Target version set to Tails_2.12

#5 Updated by intrigeri about 1 year ago

  • Assignee changed from intrigeri to anonym
  • QA Check changed from Ready for QA to Dev Needed

Meta: I'm not a big fan of the info duplication, and would prefer if we fixed the root cause of the "copious amounts of contributor docs which might scare people away" problem, but I see your point about this doc being self-contained, and I'm not ready to work on something I would find better, so I'll shut up.

However, I want this to be better integrated with our existing doc:

  • We already have an intro for new code contributors, that our current website navigation flow will send new code contributors to. But then how will they learn about this second intro doc? As said above, I won't dare asking you to merge these documents, but IMO the existing intro should at least link to the new one, no?
  • Please move the new page from the root of our website to the relevant section, i.e. somewhere under contribute/how/code.

#6 Updated by anonym about 1 year ago

  • Assignee changed from anonym to intrigeri
  • QA Check changed from Dev Needed to Ready for QA

intrigeri wrote:

Meta: I'm not a big fan of the info duplication

Me neither, of course. :)

and would prefer if we fixed the root cause of the "copious amounts of contributor docs which might scare people away" problem, but I see your point about this doc being self-contained, and I'm not ready to work on something I would find better, so I'll shut up.

I guess the issue with the current code contribution docs is that it doesn't easily separate the "how to hack Tails and build it" from the "go through this process to find a ticket and then follow this process when submitting your work"; my fear is that if I had to wade through the latter when I'm excited about coding and just need the former, that excitement would go away.

However, I want this to be better integrated with our existing doc:

  • We already have an intro for new code contributors, that our current website navigation flow will send new code contributors to. But then how will they learn about this second intro doc?

Speaking for myself, Tails might have been the only project where I initially read the build instructions (and similar) somewhere else than a plaintext document in the source root directory, like ./HACKING, ./README or ./README.md. But I agree it could be referenced from other places, like the code contribution docs.

As said above, I won't dare asking you to merge these documents, but IMO the existing intro should at least link to the new one, no?

Done, but I could only link to it with [[HACKING]] and not [[HACKING|short coding introduction]] which I thought would be better. Did I hit an ikiwiki bug?

  • Please move the new page from the root of our website to the relevant section, i.e. somewhere under contribute/how/code.

Done!

#7 Updated by intrigeri about 1 year ago

  • Assignee changed from intrigeri to anonym
  • QA Check changed from Ready for QA to Dev Needed

As said above, I won't dare asking you to merge these documents, but IMO the existing intro should at least link to the new one, no?

Done, but I could only link to it with [[HACKING]] and not [[HACKING|short coding introduction]] which I thought would be better. Did I hit an ikiwiki bug?

And what about [[short coding introduction|HACKING]]?

If that doesn't work, please describe exactly what you did and what's the outcome.

#8 Updated by anonym about 1 year ago

  • Assignee changed from anonym to intrigeri
  • QA Check changed from Dev Needed to Ready for QA

intrigeri wrote:

As said above, I won't dare asking you to merge these documents, but IMO the existing intro should at least link to the new one, no?

Done, but I could only link to it with [[HACKING]] and not [[HACKING|short coding introduction]] which I thought would be better. Did I hit an ikiwiki bug?

And what about [[short coding introduction|HACKING]]?

LOL. Fixed!

#9 Updated by intrigeri about 1 year ago

  • Target version changed from Tails_2.12 to Tails_3.0

#10 Updated by intrigeri 12 months ago

  • Assignee changed from intrigeri to anonym
  • QA Check changed from Ready for QA to Dev Needed

Excellent, thanks! I like it much more now :)

Before we merge this, I would like a tiny bit more cross-linking, so that this document isn't a dead-end for its readers, and they have a chance to learn about the more complete version of some of its bits:

  • "Git branch organization" should point to contribute/git
  • config/APT_snapshots.d/ should point to contribute/APT_repository

Feel free to merge yourself once this is done :)

#11 Updated by anonym 12 months ago

  • Status changed from In Progress to Resolved
  • Assignee deleted (anonym)
  • Target version changed from Tails_3.0 to Tails_3.0~rc1
  • % Done changed from 50 to 100
  • QA Check changed from Dev Needed to Pass

intrigeri wrote:

Excellent, thanks! I like it much more now :)

Before we merge this, I would like a tiny bit more cross-linking, so that this document isn't a dead-end for its readers, and they have a chance to learn about the more complete version of some of its bits:

  • "Git branch organization" should point to contribute/git
  • config/APT_snapshots.d/ should point to contribute/APT_repository

Done! Thanks for your input!

Feel free to merge yourself once this is done :)

Done!

Also available in: Atom PDF