Citation Style Language

Revisiting Planning, Development Process, GitHub Projects

As we’ve now, I think, figured out the question of how to add intext or narrative citation styling to CSL, the obvious question is the process by which we get from here (the solution) to there (deployment).

This has been a long-running question, as @Rintze_Zelle laid out here.

I suggest there that we make use of github’s project feature, and consolidate that on the schema repo.

Here’s how the doom emacs project uses it.

What do you all think?

Suggestions on what those project cards should be, and projects beyond a “Development Roadmap” one?

More on project cards and automation. We can setup things to require review, for example, and then condition actions based on that.

https://help.github.com/en/github/managing-your-work-on-github/about-automation-for-project-boards

Here’s a screenshot to setup automation, with a review requirement (though I haven’t yet figured out how to configure who are reviewers, and how many reviewers are required for approval).

Thanks for bringing this up again.

I am in favor of this suggestion.

So, we need to consolidate all CSL related issues in one place. Any objections? Currently, it seems to be scattered all over the place, things being discussed at multiple places. Obviously, that’s not quite ideal. Schema would be a good place.

It also occurs to me we really need the spec in the same place as the schema, so that the process for feature proposals is really a PR, with patches for schema and spec.

Right?

The spec is currently in the “documentation” repo.

Could we just move the documentation repo to the schema repo, either as a submodule (though not sure if this helps in terms of management going forward), or directly as a subdirectory?

I actually don’t know where the spec is!

Here’s how to setup reviewers.

https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/managing-code-review-assignment-for-your-team

I think ideally, we need to require reviews from some number of the core CSL team, and maybe some number of non-core implementers.

If I read the docs correctly, we could setup “teams” for those two groups, and then configure the review process.

Maybe even add a third group for @Frank_Bennett - who is both a core team member, and a key implementer. But this would assume he would be required alone to approve everything, which may not be super practical for him.

Obviously, we’d need some clear ground rules to setup this up correctly, but it seems like it could dramatically simplify our work.

Concering the stacks: The doom example you’ve linked is good. Or, we use a more fine grained approach:

One Project for the assessment of features: Proposed, Rejected, Approved, Assigned (to a release)
Then, one project for each release: To Do, In Progress, Done
(But perhaps this is overkill…)

Why not start with one board “Roadmap”, and—once we start having a new release every other month—add new projects for individual releases?

I like this idea.

I’m going to setup the roadmap project on the schema repo to experiment. We can always delete it if it doesn’t work for some reason.

Here’s the roadmap project, where I added the feature issue under discussion last couple days (though wondering if maybe just PRs should go here?)

Flagging this for @Rintze_Zelle @Sebastian_Karcher @Frank_Bennett @bwiernik @cormacrelf in particular; core team members plus a couple of people active in recent CSL work and development discussions.

But please, anyone interested in this question should comment.

I’ve had a look at the project board. I’m not sure what the “done” stack is supposed to mean. Does that mean implemented? Or accepted?
Doom’s solution looks better to me. After review we’d need a stack for rejected proposals, another for accepted proposals, but yet unassigned proposals. Accepted proposals should then be assigned to a release.
What do you think?

But, the question how a proposal is to be accepted has still to be answered.
Another question: Who is going to add issues to that board. Everyone? Team members? Do we want to have the discussion about features there? Or should discussion about the usefullness of features take place here, github issues being reserved for actual implementation details…

I just used the default, and added two version columns. Definitely intending to change that.

These are the key questions, and I’m not sure. I hope others will respond to them.

But some possibilities to consider:

I think we need people (which is not me) following tickets in last couple years relatively closely to know what issues should be put on which columns (what you call stacks).

I would suggest they do that, so triaging things we’re approving (or considering approving), things we’re rejecting, etc.

Maybe when that’s done, they could post a thread here updating on that, and encouraging people to review and make any recommendations?

I updated some of the column names away from the defaults.

I think the idea of this workflow is once something specific is approved and implemented (in my idea, schema and documentation patches merged to develop), it first moves to “done” column automatically, and then when assigned to a release, goes to the version column.

So the intext thing, once accepted, would ultimately end up on the v2.0 column.

I think.

PS - note how the roadmap status is updated on the included ticket.

Hmm, but how will you say something is accepted and planned for release 2.7 (but no coding has been done yet…)

No idea, but we need to answer that obviously.

Here’s an excellent article on some of the finepoints of setting up projects (including hooks into the label system). So among other things, we’d want to revisit the existing labels, and then set them up to tightly integrate with the project.

And here’s the code he uses in the article; seems there may be similar code around github to extend the functionality.

I missed that there are organization-wide projects in github (which is probably what we need), and that rintze already set one for 1.1!

https://github.com/orgs/citation-style-language/projects/1

Seems to be private though; maybe because he was just testing.

Perhaps it’s easier to address the easier problem first. Why don’t we start centralizing all issues in one place? I wouldn’t mind if’s in evolution or in schema. The need to centralize the issues should be fairly uncontroversial. (I don’t know how easy that is. Can we just move the issues or do we need to create new issues?)

Actually, turns out we don’t need to. Here’s the search interface within the CSL org project, searching across repos.