Replies: 4 comments 10 replies
-
|
I'm glad to hear you've found SILE to be useful, and also that you you want to contribute. Don't be shy about jumping in. Feel free to work on whatever area scratches your itches. Yes things are a little disorganized as far as how / what folks can contribute. In fact if you feel the lack of some specific guideline perhaps that can be a contribution. Just a few non-exhaustive notes:
As for a list of desires / needs: that's what the issue tracker is for, not the README. We have lots of feature requests and know bugs. We also have some issues grouped into projects and have a few issues discussing what the goal are for milestones, such as #1398. Personally I don't think issue and PR templates are very useful and find them frustratingly restrictive on most projects. They are mostly useful for weeding out low-quality reports that don't include relevant information, but we're not exactly flooded with those at this stage. If you can think of some specific template bits that would be useful to contributors then I'm open to hearing about it. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for your answer and patience. I admit that firstly I found myself a bit shy about coming here and proposing stuff, like being somewhat annoying by request reviews and/or asking too much... Anyway, since the doors seem to be open, I'll take a look at these projects, make other PRs I've been thinking about and engage more. I made a PR to the package template (sile-typesetter/package-template.sile#2), unfortunately I made two, because when did the first still didn't know how to fix things I'd like do change without making another PR 🤦, so sorry for have polluted the repo's history. Can you review it? |
Beta Was this translation helpful? Give feedback.
-
|
No worry, we all learn how to do things. But yes you can ammend existing PRs by adding more commits to the same branch and pushing again, or even rewriting history and force pushing the branch. Nothing is considered immutable until it's merged to a protected release branch. |
Beta Was this translation helpful? Give feedback.
-
Rather than the README, I'd suggest using the Wiki pages -- also a great way to revive them, and discuss our options. |
Beta Was this translation helpful? Give feedback.
-
|
@jodros @alerque I added a "Contributing" section to the Wiki, with some of the things from this discussion. On my way, I also reorganized and extended the FAQ (with new items on input formats, etc.) I'm interested in your feedback, and perhaps we can make this Wiki much better and useful! |
Beta Was this translation helpful? Give feedback.
-
|
I have just added a "Regarding questions" to the Contributing guidelines on the Wiki. |
Beta Was this translation helpful? Give feedback.
-
|
... Also added a FAQ item on overflowing lines, as I've seen this question more than once. |
Beta Was this translation helpful? Give feedback.
-
@alerque Unless I'm mistaken, only organization owners can create "public" project. Can we possibly get the following projects:
|
Beta Was this translation helpful? Give feedback.
-
|
Beta Was this translation helpful? Give feedback.
-
|
I opened some new projects, but it seems to be any of these groupings without a clear end point would be better off as labels not projects. I saved the "SIL syntax" one for that, but possibly the "Bibliography" issues might not actually be a project too, more of a label thing. Thoughts? Also it seems like all new projects are private by default and I have to change them later, so if you can open them that's fine. We can fix the visibility after the fact. |
Beta Was this translation helpful? Give feedback.
-
I like it :) |
Beta Was this translation helpful? Give feedback.
-
|
I added a labels inputters:sil , inputters:xml and packages:bibliography . We can of course add more as needed. |
Beta Was this translation helpful? Give feedback.
-
|
I’d like to contribute a broader thought to this discussion, one that has been on my mind for a long time and feels especially relevant here. Aside from addressing bugs or implementing small specific improvements, it's common for contributors — especially newer or casual ones — to propose features somewhat arbitrarily, without anchoring their suggestions in a real-world context or specific need. In my view, one should always begin with a real typesetting project as the foundation. Have something tangible to typeset, and when you encounter a problem in that process, then work on solving it. This hands-on approach is not just practical: it’s the most effective way to deeply understand both the nature of the problem and the eventual solution (and its limits!) In fact, you don’t even need to formally integrate "immediately" your solution into the core software. For instance, my own experience with a better bibliography management system arose from a project where the existing system was insufficient. I developed a solution, and even published a book made with it, though the main distribution hasn’t adopted it yet. On my way, I learned a lot about the problem and the solution, and I could share that knowledge with others, "upstream". The key point here is context: tackling real projects enables you to better grasp the nuances of both the problem and its resolution. Only then can you start thinking about generalizations that could be beneficial for others. In contrast, when feature suggestions are proposed without a real project as a reference — simply because they seem appealing in theory — it becomes difficult to assess whether they would actually be valuable in practice. Without that context, understanding both the necessity and the potential impact of the feature is much harder. TL;DR: Start with a real project, identify a problem, and then work on solving it. This approach is more effective and leads to better solutions. No project in mind? No problem, just pick something that piques your curiosity. It doesn’t have to be something you’re deeply invested in right now. Do you think I’m personally passionate about the mechanics of black holes? (Spoiler: I’m not — but heh). The point is to choose a challenge, and you’ll learn along the way. Because sometimes, the best learning comes from experimenting in areas you wouldn’t normally explore. You might stumble upon a fascinating problem you never expected, and that’s where real growth and innovation happen. Whether it’s typesetting a recipe, a poem, or a scientific article — just take on something, and you’ll find yourself learning both the system and the nuances of the content.1 TL;DR: So don’t overthink it. Pick a random subject, tackle the challenge, and see what you can create. Since I mentioned tackling some of the math involved in black hole mechanics as a challenge — just for fun — and my true need for an improved bibliography system in a real project, it’s interesting how things sometimes intersect in unexpected ways...
TL;DR: You never really know where these explorations might take you… but that’s part of the excitement! How would have I done the above entry without SILE's math?2 Footnotes
|
Beta Was this translation helpful? Give feedback.
-
|
Yes. From my own experience I can say the workflow I find most beneficial when coding (whether related to publishing with SILE or other) is to hack something together the first time I encounter a problem that just gives the expected result, then the second time I encounter a similar problem I copy and paste again but overhaul the code a bit to clean up whatever rough edges are obvious to future me. Then the third time I hit a similar problem I step back and write a generalized solution, go back and replace it in the last two cases plus my current one and try to think about an interface that is robust enough to keep using. The code I've hacked together to cover a general problem the first time I encountered it is never as good as the code that has survived use and adapted in real projects a couple times. On a slight counter point, one thing about FOSS is that the process of getting to that more robust code can often involved more than one party. Somebody may (and is welcome to) contribute their first attempt at hacking something together and the extra layers of review in the contribution process should involve other eyes thinking about how the proposed solution generalizes. Also (as just happened e.g. with the folios error PR #1943) it is okay to bring up and propose thing and for the answer sometimes to be "this isn't a problem we want solved that way at all". In that case the proposed solution was to make the error go away, but that does not generalize because the error actually serves a purpose for some scenarios. |
Beta Was this translation helpful? Give feedback.
-
Since SILE has been pretty useful to me for the last months, I'd like to be an usual contributor of this project as a whole - not only the core typesetter, but I'm missing any guidelines to follow. The documentation explains greatly how to extend it for one's own use, but when it comes to actually contributing, it doesn't.
For example:
Another important step to do so would be to have a list of the main enhancements desired in README.md, for everyone who had contact with SILE be aware of the needs of the project. I suppose many people use to contribute just adding what they found missing for their own needs, but if someone just wants to do something more, this kind of road map would be great.
As we can see here in the Community standards, besides a general guideline for contributors, we also miss templates for issues and PRs.
Beta Was this translation helpful? Give feedback.
All reactions