Editing Documentation (for Dummies)

Discussion Discuss FreeSewing development & code
1

OK. deep breath.

I want to help freesewing.eu by fixing some of the excellent documentation you folks created. I went through the entire FreeSewing Editor documentation and there are a bunch of minor fixes that I would like to contribute (typos, grammar, word choice, cut-and-paste errors, labels incorrect, that sort of thing). Starting simple & trying not to mess anything up.

I noticed the big “Edit this page” button at the bottom of each FreeSewing.eu documentation page. And I thought, “oh, cool, they have a built-in editor! This’ll be so easy!”. :slight_smile:

And of course that brings you to Codeberg and the specific page within the “develop” branch. I was a software developer, but I’m a little rusty on Git. So I went to freeSewing.dev and I’m about a third of the way through Joost’s excellent Git Training. And I have Xcode on my Mac and made sure I had git locally (I do). But I’m used to Xcode doing all the version control work for me via the GUI, and I thought Xcode was overkill for a little light editing, so I found Gram, a Zed editor fork that looks super easy to use & lightweight, unlike Xcode. And it supposedly integrates with Codeberg.

So the file I’m trying to edit is an .mdx file, so I researched what that was, then created a little MarkDown cheat sheet to remind myself all the ways to format text, so I’d understand what I was trying to edit.

So then I created a Codeberg account and forked FreeSewing. And rather than create a repository on my local hard drive, I thought “maybe I can use the Codeberg website to edit & commit a file with some very simple changes, just to make sure I understand what I’m doing.” So I clicked the edit button (the file I’m actually editing is sites/org/docs/docs/editor/views/designs/readme.mdx) and it let me make a couple minor edits. So I filled out the commit comment, selected “create a new branch & start a pull request”. But as I go further down that path, I think I created a pull request in my own repository? Was that necessary? Or only when I try to push my repository changes to FreeSewing’s develop branch? I suppose I need to finish reading Joost’s git documentation. :slight_smile:

But am I going down the right path here? Am I almost there? deep breath

Eventually I’ll do this all locally with Gram, but I was just trying to test out the web workflow at Codeberg.

2

Yes, you’re on a right path. There are more ways that lead to Rome, and the one you’re on is a good one. We prefer people create their own fork and make branches in there. Then you can make a PR from that branch to the Freesewing/develop branch. And once it is there, we can merge it with the main branch and publish it. Keeping your things separate in your own fork is a good way to keep things organized.

Do make sure someone isn’t working on what you’re trying to fix. One of the ways to do so is by creating an issue for something you found or want to improve and assigning that to yourself. And before you’re starting to work on something, check if there isn’t an issue for it already.

2 Likes
3

PS. Don’t delete your branch after you made a PR that still needs to be merged. Not a good idea. Don’t ask me how I know.

2 Likes
4

When we hosted the code back at Github, this was functioning a bit better, because Github has a pretty good web editor, you just need to login, edit the file and “save it”, which more or less automatically creates a commit and pull request and stuff. This is a bit (way!) more primitive on Codeberg. Maybe this will be improved in the future.

Of course Codeberg is better because it’s using open source software, it’s EU-hosted and not part of Microsoft and their AI stuff.

3 Likes
5

Haha, I just about spit my oatmeal out! # beentheredonethat

Thanks for your advice.

6

Oh, don’t worry, I avoid anything Microsoft touches like the plague. The extra work on Codeberg is no problem. Codeberg will probably make it easier to do as soon as I get the current process figured out. :slight_smile:

7

OK, I’ll do that for my next set of changes.

The changes I’m trying to commit now are just two words that obviously need to be changed, and if someone’s done it already, that’s fine. I’m really just trying to make sure I do the process correctly, since I’ve never use Codeberg before and my version control experience is a little rusty. Think of it as me doing a muslin for a new pattern I’m trying out! :zany_face:

1 Like