Looking at the documentation, I once again had that feeling I should try to help to improve that some. Here I’m like setting up to develop/contribute, even if it might be limited to some documentation changes …

idk.git.i2p

It seems that development for i2p is now completely (possible) in gitlab. So there is not only the source code there, but also management of changes and tickets. I’m unaware if this now solely taking place this way, but for me getting into monotone and trac years ago was too steep to actually get anywhere in the end. So sounds like good news to me - let’s see …

Account

So, for this gitlab I need an account in that gitlab. If you do this, pay attention to the message telling you not to use your @mail.i2p address for this (needs clearnet or will not work I guess?).

Next step is to upload the ssh-key (the public part of course) to git. Without that, the system wouldn’t be able to verify the account when connecting via ssh - hence there wouldn’t be any write access …

Fork

As I’m not an i2p-dev (technically in terms of permissions anyways), I cannot change the orginial repository at all. Aside from tickets maybe, but those are actually not held in the repository itself far as I know..

The workflow therefore typically includes forking the project as a first step. This copies the content to a project one owns. That’s where changes are to be made then. This (and the following) is described in a i2p-blog-post on the official site.

Cloning

Cloning needs setting up a tunnel for the ssh-transport (different port on the target host hence different tunnel needed in i2p). After setting this up (see i2p-blog-post) so that it would be reachable from my LAN I started it, and then set up my ssh-config accordingly:

lbt@go:~$ vim .ssh/config
Host git.idk.i2p
        HostName                192.168.11.11
        Port                    54241
        IdentityFile            ~/.ssh/id_ed25519_lbt_git

This will make git.idk.i2p point to the host/port of the tunnel that I created in the step before while using ssh.

Now, let’s see … This should allow us to use git from the command-line with the .i2p address right away:

lbt@go:~/synced-git.idk.i2p$ git clone git@git.idk.i2p:lbt/i2p.www.git
Cloning into 'i2p.www'...
remote: Enumerating objects: 53293, done.
remote: Counting objects: 100% (1049/1049), done.
remote: Compressing objects: 100% (294/294), done.
remote: Total 53293 (delta 723), reused 1049 (delta 723), pack-reused 52244
Receiving objects: 100% (53293/53293), 246.34 MiB | 144.00 KiB/s, done.
Resolving deltas: 100% (38715/38715), done.

Got nothing to verify the ssh fingerprint against, but as I did setup the tunnel to an i2p b32-address, this should be ok anyways. Actually relieving for once not having to verify them (although this has gotten easy as one can just copy-paste it and doesn’t have to look at strangely looking strings no more).

Anyways, this took a good while - but it worked! I remember that git not being able to resume downloads was the argument why the team wasn’t switching to git when I asked about it years ago ;)

Branching, Changing and Committing

The actual change I’m aiming for today was incredibly small - just changing “Trac is still available” into something saying it’s not anymore. Following the suggested workflow I next needed a feature-branch to work in:

lbt@go:~/synced-git.idk.i2p/i2p.www$ git checkout -b trac-is-gone
Switched to a new branch 'trac-is-gone'

To make my change I just edited the according file then:

lbt@go:~/synced-git.idk.i2p/i2p.www$ vim i2p2www/pages/site/get-involved/guides/new-developers.html
[...]
lbt@go:~/synced-git.idk.i2p/i2p.www$ git add .
lbt@go:~/synced-git.idk.i2p/i2p.www$ git commit
[trac-is-gone 4a4c4800] Text update to reflect the old Trac isn't available anymore
 1 file changed, 2 insertions(+), 2 deletions(-)

I actually changed a second thing as well there, where the link to the issues at GitLab was still described as “Trac”. Anyhows, the last two steps were adding the changed file to what to commit, and then committing that to my trac-is-gone branch (as it is the current branch there).

I also noticed that the URLs inside the document are handled by variables and that the variable to hold the URL for the development-site is still named trac albeit pointing to git now. But as I’m not familiar with variables and their handling/side-effects in that context, yet, I’m gonna go ahead with my minimal changes as a first step. Might look into that other stuff at some point then …

Managing the Upstreams

The mentioned blog-post suggest to add a second upstream (pointing to the original) as this is needed to pull changes that are made there. That allows (necessitates?) to specify which upstream to use furthe on then …

lbt@go:~/synced-git.idk.i2p/i2p.www$ git remote add upstream git@git.idk.i2p:i2p-hackers/i2p.www.git

The address is basically the same as mine, just using i2p-hackers instead of my lbt there. I first used to it check if any changes were made in the meantime:

lbt@go:~/synced-git.idk.i2p/i2p.www$ git pull upstream master
remote: Enumerating objects: 15, done.
remote: Counting objects: 100% (15/15), done.
remote: Compressing objects: 100% (8/8), done.
remote: Total 8 (delta 7), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (8/8), 1.92 KiB | 982.00 KiB/s, done.
From git.idk.i2p:i2p-hackers/i2p.www
 * branch              master     -> FETCH_HEAD
 * [new branch]        master     -> upstream/master
Merge made by the 'recursive' strategy.
 i2p2www/pages/site/docs/api/samv3.html | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

And of course a change had already been made in the meantime ;) No problem, though, as it wasn’t contradicting what I changed. Exactly where version management shines …

So, let’s “push it”:

lbt@go:~/synced-git.idk.i2p/i2p.www$ git push origin trac-is-gone
Enumerating objects: 31, done.
Counting objects: 100% (31/31), done.
Delta compression using up to 12 threads
Compressing objects: 100% (21/21), done.
Writing objects: 100% (21/21), 3.08 KiB | 1.54 MiB/s, done.
Total 21 (delta 18), reused 0 (delta 0), pack-reused 0
remote: 
remote: To create a merge request for trac-is-gone, visit:
remote:   http://i2pgit.org/lbt/i2p.www/-/merge_requests/new?merge_request%5Bsource_branch%5D=trac-is-gone
remote: 
To git.idk.i2p:lbt/i2p.www.git
 * [new branch]        trac-is-gone -> trac-is-gone

So far I had only downloaded the upstream-change into my feature branch, but I also need to update the master branch:

lbt@go:~/synced-git.idk.i2p/i2p.www$ git checkout master
Switched to branch 'master'
Your branch is up to date with 'origin/master'.
lbt@go:~/synced-git.idk.i2p/i2p.www$ git pull upstream master
From git.idk.i2p:i2p-hackers/i2p.www
 * branch              master     -> FETCH_HEAD
Updating e4fe0e24..a68eb521
Fast-forward
 i2p2www/pages/site/docs/api/samv3.html | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

So, let’s see about the merge request …

Merge Request

The final step - and where it becomes relevant for the original project for the first time - is to ask them to have a look at what I changed and hopefully approve and integrate (merge) it. Far as I know this is solely possible using the GUI in GitLab.

For this I selected Repository > Branches > trac-is-gone in the left sidepannel there (from within my fork) and was offered a big blue button labelled “Create merge request”. The auto-selected options are

  • Delete source branch when merge request is accepted.
  • Squash commits when merge request is accepted.
  • Allow commits from members who can merge to the target branch.

Unsure of the exact relevance of these. I decided to “just go for it” and see what happens - feels like I have bothered #irc-dev with enough questions for today already. Hopefully I (at least in the long term) will help more than consume valuable time of the people actually doing the work there ;) But hey, that’s what this is/was about and one gotta start somewhere, right?

GitLab was pretty fast to display me something about “Pipeline #911 failed for 2e809dbe on lbt:trac-is-gone”. And I have no idea … Feels like it’s bashing me, it goes like “code_quality FAILED!”, “test FAILED!”, “build FAILED!”, “your shit is so bad I’ll now disable everything here”, “come back when you have understood DevOps and re-enable”. Well, kind of like that, this includes contents from mails being send in the process. Guess I’ll need to circle back to this ;)

Finishing Touch

It seems this was accepted lightning fast despite the alarms that gitlab gave me there. To get my fork current with the now officially modified upstream:

lbt@go:~/synced-git.idk.i2p/i2p.www$ git pull upstream master
remote: Enumerating objects: 16, done.
remote: Counting objects: 100% (16/16), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 9 (delta 8), reused 7 (delta 7), pack-reused 0
Unpacking objects: 100% (9/9), 841 bytes | 841.00 KiB/s, done.
From git.idk.i2p:i2p-hackers/i2p.www
 * branch              master     -> FETCH_HEAD
   a68eb521..c6aeacf4  master     -> upstream/master
Updating a68eb521..c6aeacf4
Fast-forward
 i2p2www/pages/site/get-involved/guides/new-developers.html | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

and then pushing this change to my fork:

lbt@go:~/synced-git.idk.i2p/i2p.www$ git push
Enumerating objects: 27, done.
Counting objects: 100% (27/27), done.
Delta compression using up to 12 threads
Compressing objects: 100% (17/17), done.
Writing objects: 100% (17/17), 2.77 KiB | 2.77 MiB/s, done.
Total 17 (delta 15), reused 0 (delta 0), pack-reused 0
To git.idk.i2p:lbt/i2p.www.git
   e4fe0e24..c6aeacf4  master -> master

Guess I have more or less successfully completed a change cycle. So let’s get ready for more :)

TODO: Become clear about why gitlab was complaining so much and either how to be conform or how to make it shut up ;)