Page MenuHomeSoftware Heritage

Decide where should be gathered specs
Open, HighPublic

Description

Options:

Event Timeline

moranegg triaged this task as High priority.
moranegg updated the task description. (Show Details)

I need this decision for different specs, for example:

  • Legacy software deposit
  • Sparse / Metadata deposit (now in docs)
  • Metadata workflow- How do we dill with software metadata (T1344)
zack added a comment.Tue, Apr 23, 5:46 PM

I need this decision for different specs, for example:

  • Legacy software deposit
  • Sparse / Metadata deposit (now in docs)
  • Metadata workflow- How do we dill with software metadata (T1344)

I'm not clear on why this decision is blocking for you. If it's so urgent, use whatever is easier for you, will move it somewhere else later as we have done in the past :-)

That said, I think the best place for any kind of long-term document is docs.s.o, which means a rst document in some of the current software components or swh-docs as a fallback.
While working collaboratively in the early days of a spec, though, having it on the wiki (or even a pad, really) would be easier, because the barrier for contribution is lower. Which is what has happened for most of the specs you mention: born and developed on the wiki first, moved to docs.s.o later.

If this answers your main question in this task, feel free to close it. If not, please clarify what's still missing to clarify the proposed approach.

@zack Thanks for the answer.
It's not a blocker per se but I prefer to have a long term decision before moving the specs from different spaces, so for me it's a high priority.
It wasn't clear to me that it should be in the docs and that this is the long term decision.

The problem with having it in the docs, is that specs of higher level (like metadata workflow) must be in a specific repository, or can I have a specs folder in swh-environment?

zack added a comment.Wed, Apr 24, 1:55 PM

The problem with having it in the docs, is that specs of higher level (like metadata workflow) must be in a specific repository, or can I have a specs folder in swh-environment?

That was my point about "swh-docs as a fallback". If it doesn't fit a specific repo, they can go in swh-docs, where we already have some cross-cutting material.

In T1683#31104, @zack wrote:

That was my point about "swh-docs as a fallback".

Good point, didn't understand that, my bad.
Maybe all specs should be in swh-docs even if there is a specific repo?
and have a link to and from the specs to the implementation?
This way we don't mix between functionality and implementation..

zack added a comment.Wed, Apr 24, 3:14 PM

I don't think it's a good idea to move specs from the specific components they specify to a different repository (swh-docs), because that will just increase the chances (which are already quite high) that they will get out of sync.