Skip to content

Add contributing guidelines #112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 13 commits into
base: main
Choose a base branch
from
Open

Conversation

T0mstone
Copy link
Collaborator

As mentioned in #110 (comment).

These conventions are clearly contributing guidelines, so I went with CONTRIBUTING.md for the file name. That way we can also add other contributing guidelines in the future, if we want to.

If you want to reword something or add other conventions that I may have missed, don't hesitate to leave a comment.

From my side, there's only one unresolved question left here (which I also left as a TODO comment in the file itself), namely whether we want to write something about when we choose e.g. .t.r over .tr for corners (cf. #100).

@T0mstone T0mstone added enhancement New feature or request meta Discussion about the structure of this repo labels Jul 15, 2025
Copy link
Collaborator

@MDLC01 MDLC01 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My personal view is that this document should be used as a way to quickly find precedents, but that new names should always be motivated by existing symbols. In other words, those guidelines should reflect the existing conventions and shouldn't be used as a source of truth--the only source of truth is the existing names. For this reason, I strongly believe every rule in this document should be supported by one or multiple examples. This is reflected in my proposed rephrasing of the first paragraph.

Unrelatedly, if this document aims to be contributor guidelines, it might benefit from some of the links from the "Useful links" section of the proposals document. Maybe even a link to the document itself.

@T0mstone
Copy link
Collaborator Author

Another question that should be resolved: Should .cw and .ccw be generic modifiers instead?

Or, going further, perhaps the whole distinction should be removed entirely? (Tho I personally like it.)

@T0mstone T0mstone changed the title Add conventions document Add contributing guidelines Jul 16, 2025
@T0mstone
Copy link
Collaborator Author

Changing the title to reflect the broader scope.

@T0mstone
Copy link
Collaborator Author

Also, I forgot to say this earlier: Thanks for the thorough review!

Copy link
Collaborator

@MDLC01 MDLC01 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or, going further, perhaps the whole distinction should be removed entirely?

Maybe just ordering the modifiers from most concrete to least concrete would be enough. I personally don't see a clear cut distinction.

CONTRIBUTING.md Outdated
- `.l`/`.r`/`.t`/`.b`: The four main directions (left/right/top/bottom).
- For delimiters, `.l` means opening and `.r` means closing (see [#100](https://github.com/typst/codex/pull/100)).
- `.tl`/`.tr`/`.bl`/`.br`: The four corners
<!-- TODO: Do we have or want to have conventions about when to choose `.tl` vs. `.t.l`? -->
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you mean a clarification regarding corner delimiters, I don't think this is necessary.

@T0mstone
Copy link
Collaborator Author

Maybe just ordering the modifiers from most concrete to least concrete would be enough. I personally don't see a clear cut distinction.

Hmmm, I'd like to hear the other maintainers' opinions on this. Tho I'd definitely want to order them from least to most concrete instead.

@Enivex
Copy link
Collaborator

Enivex commented Jul 18, 2025

I think it would be helpful to have them organized alphabetically, at least within a category.

@T0mstone
Copy link
Collaborator Author

T0mstone commented Jul 21, 2025

Another question that should be resolved: Should .cw and .ccw be generic modifiers instead?

I've now decided on "yes".

@T0mstone
Copy link
Collaborator Author

I think it would be helpful to have them organized alphabetically, at least within a category.

I kept some groups in the generic section that are still sort of ordered by importance, but the others are now sorted alphabetically.

@Enivex
Copy link
Collaborator

Enivex commented Jul 23, 2025

I think typst should be typeset in lowercase?

I'm wrong

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request meta Discussion about the structure of this repo
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants