Citation Style Language

CSL evolution process again


We can do that, but I’m not sure we have to. What would be a good name?

Could we just keep the old repo as an archive, sort of? And move current development to schema (o however we will call this)? In the end, I don’t think it matters much. But we will have to make sure that each closed schema PR results in an opened documentation issue. And, having two repos means having two milestones (or project boards).

I think it really depends on the purpose of the boards. The way we used them initially required a lot of manual intervention. If we use them as like milestones, it should be possible to set up automation in such a way that issues/PRs get moved automatically, e.g. when reviewers approve, an issue gets closed, etc.

On this: Should we try to come up with a simple system for labeling issues? I think we don’t need much, perhaps

Type: ???
Status: ???

I don’t think we need the priority labels though. Also, we should decide where we’ll add the version tags? Should this be done with labels? Or better with milestones or projects (whichever we will use)? Using different tools for essentially the same information seems a bit confusing to me.

In general, we need to track type, status, and scope (whether applies to schemas vs tests, etc.).

Not really sure what to do with it, but I forked the template repo, and added the scope.json file.

The milestones are useful for tracking progress associated with a release.

The labels for releases are lighter-weight annotations. I sometimes add them to suggest a target, but only add the milestone when we agree. It’s possible we could stop using them.

Projects aren’t good for the same thing. Their only value currently, in my view, is to consolidate info across repos. Probably better to remove in the end.

Keep in mind, though, the labels aren’t incorporated into the git version history; they are apart from it.

So perhaps we should a label for target? (Perhaps not in the current form with fixed version numbers, but rather just indicating whether this should go in a x.x release or a x.x.x release.) And once we have a couple of issues together we can add some of those to the next milestone?

1 Like

In that case, it’s maybe more (or also) a matter of minor vs major change?

Yep. That’s what I was thinking of. But we will need to define what these terms are supposed to mean. (What is minor, what is major? What will be major enough to warrant for 2.0? And so on…)

1 Like

Regarding this thread:

Everything minor could then always be merged into master, major into the next x.x branch, right? If yes, that sounds good.

I honestly don’t see much problem with the existing schema and documentation repo structure. The loss of git history with changing them is big, and I’m not sure the upsides outweigh that. GitHub could technically handle redirects if schema were renamed, but I don’t really see the value there. What’s unclear about schema?

1 Like

@bwiernik Ok. So you vote for keeping schema and documentation as is. What about merging evolution into schema?

And the label question? You think that would be of value?

I think csl-evolution can just be archived after the existing issues are closed. It was created at an earlier point when a good development workflow was less clear. I’d like to keep the closed issues, so I think archiving the repo rather than deleting might be better; also would be cleaner than migrating the issues to another repo.

Reserve milestones are issues/PRs that have been agreed to; these can function as a checklist to prepare a release.

In terms of labels, major/minor is probably the most important. I think that the current 1.0.2 vs 1.1 labels are reasonable for that purpose, but major and minor could be fine too. No real preference.

Could be useful to be a bit more specific, a minor issue/PR might be new_variable (including variables, types, terms), bugfix (e.g., something like the locator="sub verbo" issue that requires a minor processor change), or documentation (clarification or reconciliation of the spec/tests). A major issue/PR might be style (a major change to style behavior or a new element, something requiring changes to either processors or styles) or data (a major change to the data structure).

1 Like

Archiving is better then deleting, yes. Couldn’t we just migrate the remaining open issues already and archive the repo now? I imagine it will take some time to close some of them.


I guess in the end, both solutions will be fine. I was just thinking that major/minor has the advantage of being independent of specific releases, which should perhaps be tracked with milestones, anyway. But you’re right. It won’t matter much.

These are all useful, of course. I thought that could be covered with the type prefix mentioned above, e.g. type: bugfix, etc.

1-3. Sure.
4. Adding type: seems unnecessarily verbose.

Do you have the rights to migrate the open issues? Or someone else @Bruce_D_Arcus1 ??? Would be one more step towards a leaner process.

There is a labeler GH Action that we can setup, which will auto apply labels based on the path of the file being modified.

So you could imagine a config something like this:

input: schema/input/*.json
csl-main: schema/styles/csl.rnc
csl-terms: schema/styles/csl-terms.rnc
csl-variables: schema/styles/csl-variables.rnc
test: test/schema/*
tools: tools/*

If you guys think this is a good idea, let me know if you think the above works, or if you suggest any changes?

Are you asking about moving issues from evolution to schema?

Yes. That’s it. (Regarding evolution to schema)

Would be good to know though if there are objections… @Rintze_Zelle @Sebastian_Karcher

How exactly is that going to help us? (Regarding auto-label)
That works on PRs but not on issues, right?

When someone submits a PR, it would auto-assign the tags; so yes, only PRs.

Could use something like this for issues, in conjunction with our templates (to ensure keywords we’re looking for are there)? It can also do PRs, though on first glance not based on paths; it only looks at the commit messages.

Here’s the key config parameter content:


The hardest work is just determining the labels we want in the end!

I’d rather just finish the issues than worry about shuffling cards around

Probably right.
Perhaps we should then add the issues we want to cover to the appropriate milestone?