Formatting Code Contributions

Development
1

As the founder of Syncthing has recently written,

Yeah, no, we don’t do formatting-only changes unless there are specific circumstances.

This has me wondering, what standards of formatting do we follow when making substantive contributions then?

Are contributors of Go code, for example, free to place open-block curly braces on a separate line? Or even to mix styles within the same files?

One of my main learning styles when mentally parsing a codebase new to me, is to apply formatting conformity as I read. Thus, a result of me reading the code will tend to be formatting improvements:

  • Am I supposed to revert those changes (improvements, hopefully) after I make them?
  • Am I supposed to leave them in my own fork, where they will quickly become entirely infeasible to merge with the upstream codebase?
  • Something else?

As part of my self-introduction to the Syncthing codebase, I was applying this process to the documentation files within it, and have yet to encounter for myself an awareness of what formatting policies we do use. :thinking: Any thoughts?

1 Like
2

Go has canonical formatting by go fmt - we follow and enforce that. There isn’t anything to change there.

For everything else the point made in the PR is still valid: Formatting only changes aren’t desired. Only possible exception from my point of view: If you do want to setup/introduce automatic formatting, then that should be discussed first and then if accepted, an initial re-formatting to that standard will be necessary.
I’d suggest finding semantic things to change. I can assist with trying to find suitable bugs/features for you being new to the code. Also depends on what you want to focus on, ingesting all of the code at once isn’t really a feasible option (well I don’t know you, but I’d say for most people it’s not).

General formatting standards for docs/css/…: Similar to what you already encounter :slight_smile:
I know that’s not particularly clear, but I think that’s really it. Spending brain cycles on formatting is loosing braincycles for meaningful work.

3 Likes
3

I would be grateful for such assistance, as I would prefer to contribute features and fix bugs, rather than merely make code more visually appealing — though such improvements can hypothetically make the code more inviting to new contributors in the future.

Similar, for sure, but I have encountered anomalies. (Inconsistent formatting within the same file.) On a sufficiently grand scale, sure, it inevitably makes sense to automate regexes for imposing visual conformity across multiple source-code files.

But more to the point of what I seek to accomplish, I wish to introduce myself to to the community by describing (and better understanding for myself, and perhaps even transcending into a more capable modality) my own learning style as a programmer, which in this aspect is:
I usually need to write as I read — my ability to focus on and more-proficiently parse any given quantity of source-code files, is signifigantly stimulated by setting myself to the meta-task of applying a set of visual formatting rules to said code. It’s rather like a bridge for me, between the world of human languages and the world of machine languages.

My primary practical concern in opening this forum topic, is seeking ways of bypassing the de-motivational feeling that Syncthing has become an ossified project metaphorically hovering on a plane inaccessible to those lacking the specific skills needed in order to contribute meaningfully to it.

As it were: the paradox of can’t contribute because you don’t know enough yet versus can’t learn because you can’t contribute.

While emotion can be valuable and important, engaging my mind with the pure logic of this deterministic world (the ALU), is the means by which we accomplish wonders, and is the goal — I shall take heart even in the face of a steep learning curve.

1 Like
4

There’s no such paradox - you don’t need to know that much about Syncthing to start contributing. And I am not just making that up, I did learn Go entirely and most of my programming skills by starting to contribute to Syncthing. For me all the projects I contributed, I started by scratching my own itches: A bug that annoyed me, a small feature I wanted. I tried to find something which looked tangible to my issue, and started exploring from there until I was able to fix something. Just a suggestion :slight_smile:

If doing formatting changes is your way to familiarize yourself, you can do that. Yes the changes themselves won’t be added to the project, but if the entire purpose is to guide your learning, it still accomplished a purpose, right?

What is you motiviation to contribute to Syncthing, respectively what are your interests? Do you have something about Syncthing you want to change/improve? Do you want to learn Go? Do you want to do front-end (web-ui) work? Or database stuff?
I am just trying to get a feel for what might get you started - no need to answer all (or any) of those questions :slight_smile:

4 Likes
5

I concur that learning Go also happened when trying to find where to add a new feature to Syncthing in my case. Same with most of the web development stuff actually, like Angular, Bootstrap and even a lot of JavaScript features. I’m very happy that Go was chosen for the backend implementation, as one thing the language definitely got right is the “canonical” way to format source code by automatic means, built-in directly to the compiler. So that discussions like this just don’t need to happen, there is simply one correct style, period.

Not so much for the other languages used, but that’s alright IMHO. You tend to learn what’s appropriate (also programming patterns, not only formatting) when getting reviews on your code changes. That takes time for sure, but it’s time better spent than us sitting down and writing style guides for every miniscule detail.

If beating the code into some shape is your way to grok it, that’s fine and I can understand it to some degree. I’ve had several projects where I could not focus on how some contributed code works because the catastrophic styling was too distracting. But those were projects managed by me and it was only my own time “wasted” for this task.

I hope you can keep a positive attitude regarding Syncthing development, despite what feels like resistance and harsh push-back at first. I know it’s a welcoming community and group of maintainers and we’re always trying to encourage contributions, helping out so others can learn along the way.

I think you have not answered some of the concrete questions I had asked in the PR. There are some good points in your changes that may get accepted if you reduce the unneeded noise around them. If you can give a good explanation of why something needs different wording for example, I’m not at all opposed. Some things just make sense from my perspective, but I don’t see how others could misunderstand them. So I encourage you to engage in the review process and let’s distill the worthy changes from the PR. See it as part of the learning experience.

Besides that, I agree with what @imsodin said, describing your interests and finding a specific work item to focus on would be a good way to get acquainted with the relevant code parts. For things other than formatting-only changes, we’ll gladly help you to get going.

3 Likes
6

In short:

I feel as though if even my English is being rejected, my Go surely will be rejected.

At length:

I do enjoy catechism (“a question-and-answer style of teaching” — though that may be an apocryphal definition of the word — pun intended), so I would be pleased to explore my thoughts by answering your questions. :slight_smile:

There’s no such paradox — you don’t need to know that much about Syncthing to start contributing.

Though I enjoy the optimism of this assertion, i remain to be convinced, whereas I feel as though if even my English is being rejected, my Go surely will be rejected.

And I am not just making that up, I did learn Go entirely and most of my programming skills by starting to contribute to Syncthing.

That’s really quite impressive! I congratulate your achievement. :pray:

For me all the projects I contributed, I started by scratching my own itches: A bug that annoyed me, a small feature I wanted.

That is a concept I have considered before, but at the level of complexity and mission-critical purpose found in the Syncthing project, I have supposed that it would be too audacious to presume to make any changes to the actual code — that I would be taxing the mental resources of developers of greater skill than myself — yet this is very much akin to the objections I have received with regard to attempting to provide non-substantive (cosmetic) edits — that insubstantial pull requests are a waste of brain time to review.

I tried to find something which looked tangible to my issue, and started exploring from there until I was able to fix something. Just a suggestion :slight_smile:

Hopefully I shall manage to discover areas of opportunity to do that as well. Is it not likely that the abundance of such opportunities for self-education will decrease as a projects’ quality continues to improve?

If doing formatting changes is your way to familiarize yourself, you can do that.

I do appreciate your welcoming sentiments in this regard. It is one of the beautiful attributes of open-source software development generally, and of a concurrent-versioning system specifically, that I am free to make, have, and use, my own version(s) of popular projects — though in so doing (that is, actually using my versions) I may increase my susceptibility to security exploits! :stuck_out_tongue_winking_eye: (In that I will be unable to automate the merge-ing of patches provided by other developers in the main fork.)

Addressing your Questions

Yes the changes themselves won’t be added to the project, but if the entire purpose is to guide your learning, it still accomplished a purpose, right?

A purpose, to be sure. Whereas my life has value (and is worth improving) and the contributions I shall make to the community once educated and well-practiced in a particular area of endeavour, serve a purpose, a purpose is being accomplished, yes.

Nevertheless I experience a certain kind of futility knowing that the usable side-effects (code copyediting) of my autodidactic exercises will be discarded when they could be included in the main codebase in order to eliminate the need to repeat the work every time someone like me appears.

On the other hand, I can imagine there is a potential benefit in intentionally leaving irregularities in the source-code files (as well as the human-language documentation files, my edits to which have received similar resistance from the community) for the purpose of having some prizes in the landscape of code — for people like me to find! :thinking:

What is your motivation to contribute to Syncthing?

We work to better ourselves, and the rest of humanity. —Jean-Luc Picard

What are your interests, respectively?

I am interested in developing open-source tools for preserving data integrity and achieving the quantified self, for myself, and for those with less technical knowledge than I have.

Do you have something about Syncthing you want to change/improve?

Yes. I want to develop features for Syncthing which make it suitable for non-technical users. Most notably:

  1. Offload Only folders, to allow users to use Syncthing continuously on mobile devices.

  2. Graphical Selective Sync to eliminate the need to for users to understand regex.

  3. Grouping of Devices and Folders within the Bootstrap web GUI.

Do you want to learn Go?

Maybe. :slight_smile: As someone who feels more at home in C-like syntax than, say, Lua or Python, I appreciate languages such as C#, which take C-like syntax and provide a higher-level language with many advantages, such as garbage collection — and as another poster has mentioned regarding Go while I am writing this: canonical formatting automated within the compiler — and Go seems to be a good example of just such a language. So, I think I should be very encouraged to anticipate that Go will be a language I soon enjoy more than C++.

Do you want to do front-end (web-ui) work? Or database stuff?

The web GUI. In accordance with the object-oriented principle of encapsulation, I trust that many vastly more-knowledgeable minds than my own have examined the source-code to those modules such as the database-end of things, and that they will work safely and reliably — akin to the concept of the famous danger of rolling one’s own cryptographic libraries.

Overall Tone

I am just trying to get a feel for what might get you started — no need to answer all (or any) of those questions

Thank you for the no-pressure / hakuna matata perspective. I do actually feel very welcomed by the community, in much the same way one’s face feels pressed against the mat when joining a dojo — it might not be describable as comfortable, however it is an intuitive prescience of forthcoming skill, and a haptic indicator the camaraderie that one is in fact welcome in the group. (Otherwise the newcomer would be exiled from the arena rather than pinned against its floor.)

7

Your writing here sounds almost philosophical in some places. I think most of the other developers are interested in concrete technical details and not so much in meta discussions. Just as a hint what you might spend your time thinking and writing about in order to engage best with the folks here.

Your feature suggestions are certainly worth discussing and at the same time, some of them will require skills and understanding of the code base that are hard to master when just getting started on the project. Some have even been discussed at length previously and the main reason why they’re not yet implemented is lack of time and interested developers, or plainly because they are technically hard to get right. Some ideas just don’t fit the direction of the project as envisioned by the current maintainers, and usually for very good reasons. My first ideas after getting to know Syncthing were from the latter category as well.

One place to start getting involved would be to read through the open issues on GitHub and get a feel for some things previously discussed. For the “ignoring files without writing regex” idea, there is even an almost complete pull request which just stalled a couple of months ago, presumably because of lack of time from its author. You could start looking at that and build from there. It’s a nice example of how stuff can be discussed until ready for inclusion and the arguments made in the PR discussion are a good source to learn from as well.

Regarding open questions: I was talking specifically about my review comments at https://github.com/syncthing/syncthing/pull/8166

1 Like
8

It very much is. :smile: I’m greatful for the oppotrunity to be stimulated to write these sorts of autobiographical philosophical essays. It’s really helping me think better. In other words, “I’m useless without a studio audance.” —Gordon Deitrich

1 Like
9

That is a very encouraging thought. I shall have to examine that list a bit more closely! :grinning:

1 Like