I’m a FLOSS/linux enthusiast. Over the years I have learned some scripting, and can get around in git. Occasionally I fork someone else’s project to suit it to myself. Shell scripts, webapps, browser extensions etc. The kind of thing you can work in the source of without actual programming knowledge by just looking at text files.

Recently I modified a C program to have more legible/useful (to me) terminal output. I gave it a slightly different name and for compatibility have both versions running on my system. For my use-case it is a huge improvement over the original so I want to have it publicly available where I can install it from any system. And to share in case anyone else would enjoy it.

I don’t think my changes would be appreciated by the original maintainer. For one thing, no changes have been made to the code in >10 years. The dev is still active so I guess the program is considered complete. For another, my changes are breaking and specifically disrupt the “linux philosophy” aspect of the program. I think having both version co-exist is the best way.

  • I don’t want to confuse anyone who is trying to find the repo of the original program.
    • The original is hosted on github whereas I use codeberg; so the “forked from” relationship is not as clear as if I stayed on github
  • I ?do? want to update documentation such as README in the repo to describe my changes and relationship to the original
  • I ?do? want to update and --help/man in the terminal to reflect the fork’s name and possibly clarify how it works
  • Should I make some sort of courtesy PR or repo issue offering my changes even though I think it would be (even should be) rejected/ignored? It seems kind of time wasting.
  • In the case where the original upstream was being updated, how do I integrate those with my changes? I’ve had some luck so far with doing my best to guess about the git process, I think using branch, sync, merge. But I couldn’t tell you more than that. Any insight on how this is supposed to go? I have spent lots of time wading through git’s documentation but still find the main ideas kind of confusing.
  • Anything else to consider?

Since I’m just dabbling, I try to stay away from more complicated workflows, or those which require specific system set up, when possible. My experience is that when I come back to it in a few months, a year or two years, I will have forgotten a lot; it might be a different system environment. I need to be able to re-learn everything at a later time. Simple solutions that are widely-compatible, and do not rely on my memory are preferred.

I don’t mind doing a bit more work than is strictly required to learn about the FLOSS process. I’ve done it a few times before and it is useful to me to understand things.

  • Xanza@lemm.eeEnglish
    26·
    2 days ago

    IMO, if the project is open source, no courtesy is required. Specifically if the original maintainer hasn’t done anything with the repo in a decade.

    Fork it, make your changes, and if you’re feeling generous in the readme drop the link for the original repo giving credit to the author. Anything more than that is above and beyond.

    In the case where the original upstream was being updated, how do I integrate those with my changes?

    #> cd project.git
#> git fetch upstream
#> git merge upstream/main

    Read more here.

  • PhilipTheBucket@ponder.cat
    9·
    2 days ago
    • I would give it a similar but distinct name, and just be aboveboard in the docs about where people can find the original project, what the differences are, and about what’s going on. As long as you’re open about what’s up I think it would be hard for any reasonable person to take offense if you prefer a less unixy style of output or whatever.
    • I would create an issue on the original project just explaining what you like and what you implemented in the new one, and saying you’re happy to contribute although the changes may not be wanted et cetera. Just be honest. You’re fine. More communication is usually a good thing.
    • git is powerful. It’s worth learning about the concepts if you do decide to invest the effort. You don’t have to get into a crazy workflow, but having your own ongoing branch and being able to merge/rebase changes from upstream as they happen can make your life easier. However, like a lot of tools from that type of toolbox, it can also make your life a lot harder if you’re not certain of what you’re doing, so YMMV. I would try to read a specific guide about how to set up the workflow you want, not just the reference documentation. Git has a ton of features, 90+% of which you don’t need, and many of its core features are called strange things or work in an unintuitive way.
  • N0x0n@lemmy.ml
    6·
    2 days ago

    I will have forgotten a lot; it might be a different system environment. I need to be able to re-learn everything at a later time. Simple solutions that are widely-compatible, and do not rely on my memory are preferred.

    I don’t know if you have already considered it, but you can use a git repository as documentation tool ! It’s a GitHub flavored markdown syntax though.

    Fork the project, upload it to your own git repo (self-hosted codeberg, codeberg, github… Pick your poison :p) and add your own wiki documentation about your changes in the code.

    The only thing you should keep an eye on is probably the license? But I’m not the right person to discuss about licensing :/

    • some@programming.devOPEnglish
      2·
      2 days ago

      Is there any specific reason to keep the docs in the wiki section? Vs markdown documents right in the wiki itself?

      For my self I like to document in the code itself. It has one major benefit which is: I always know where the information is to be found. But there are some problems with it such as

      • creates conflicts when merging changes from another repo or branch

      • it makes the git history a lot messier because you have some commits on functional code and some on comments, all mixed up in a single document. I know with fancier git this could be tidier but I can’t reliably work at such a high skill level

      • comments are not subject to syntax formatting so harder to read

      • source document itself becomes too long to read and hard to understand

      • extremely contextual to my skills and challenges at the time when I wrote the code; not what I will need to know in the future and not what others need to know

      So not always the way to go.

      • N0x0n@lemmy.ml
        2·
        1 day ago

        Is there any specific reason to keep the docs in the wiki section? Vs markdown documents right in the wiki itself?

        I don’t know sorry :/ I do use a document but only because I want more control over the TOC (Table of content), which is a bit strange in the wiki itself, but that’s just personal taste !

        I’m not a Dev so take everything I say with a grain of salt, but what I would do is add a comment in the code to specify the change and link to your documentation file for more details (if needed). That’s probably one of the advantage of having your documentation not in the wiki page.

        This would keep your code page clean while having proper documtation in the same repo ! However, I have never seen any project doing it like that (for a good reason probably?).

        Here is my codeberg documentation repo about anime encoding in av1. It’s probably not what you’re looking for but maybe this can give you any idea or see if this could fit your workflow?

        • some@programming.devOPEnglish
          1·
          1 day ago

          but what I would do is add a comment in the code to specify the change and link to your documentation file for more details (if needed).

          However, I have never seen any project doing it like that (for a good reason probably?).

          I think what happens to me is that I completely lack discipline about structure and will often decide to re-organize things. So then I will tidy the documentation section which breaks links and nothing can be found. I would only be able to behave differently if I was very confident about what I will do and how I will do it from the outset; otherwise it is unavoidable part of learning and changing ideas through the life of a project.

          One slightly more stable system I’ve had for my own code is to use the Issues tracker as a sort of documentation storage system. Open an Issue against the repo for everything I did, keep all notes in the Issue, and link to that by number like #1, which all the forges understand as special notation so it gets picked up in useful ways in terms of references.

          I don’t do this too often because it’s a mess if anyone else ever wanted to utilize the Issue tracker and not what the Issues are for. Not to mention embarrassing. But I’ve resorted to it in situations where I had a huge amount of learning to do. With the idea that potentially could move the actual end project to a separate, cleaner repo once it was presentable, but I’ll cross that bridge when I get to it. I will say that despite being an abuse of the Issues tracker it has stood the test of time and I can go back to stuff I was working on years ago and find information stored in this way.

          But with a regular fork that is made on the same platform as the original (eg forking a github repo to another github repo), you don’t actually get an Issues tracker; only the upstream can have Issues. So it’s a bit moot.

          It’s probably not what you’re looking for but maybe this can give you any idea or see if this could fit your workflow?

          Thanks for sharing. :) I hope you don’t mind me saying this but it’s nice to see commits like “Just a commit test”. I also have these as part of learning git.

          I didn’t know we could use callouts like this in codeberg MD. Cool!

          > [!CAUTION]  
> Sometimes...
          • N0x0n@lemmy.ml
            1·
            12 hours ago

            I think what happens to me is that I completely lack discipline about structure and will often decide to re-organize things.

            Haha ! Same boat here !

            One slightly more stable system I’ve had for my own code is to use the Issues tracker as a sort of documentation storage system.

            That’s a very nice tip, thank you ! That’s something I will explore.

            Thanks for sharing. :) I hope you don’t mind me saying this but it’s nice to see commits like “Just a commit test”. I also have these as part of learning git.

            Yeah that’s a bit embarrassing 🫠 ! Was playing around with some script to convert Obsidian markdown links to GitHub flavored markdown. Because a comment is necessary to push the commit I have always no idea what to put in there xDD.

            Sorry I couldn’t help you out more and hope you will find a workflow that works for you ! 👍