status of cabal file in Git

[stefjoosten]

Version of ampersand that was used

This issue is about commit 3c55e87.

What I expected

Since we use stack to build Ampersand, the build configuration is in the files stack.yaml and package.yaml (in the root of the project directory). I think that stack generates the file ampersand.cabal.

What happened instead

I see that ampersand.cabal is part of the Ampersand repository in Git. I even see that @Michiel-s has edited ampersand.cabal in commit 3c55e87. If what I think is true, this must be a mistake.

Resolution

@hanjoosten can you enlighten us with the truth and explain what is going on? What are the correct measures? Does this mean we should remove ampersand.cabal from the Ampersand repository in Git? Does this mean we should add ampersand.cabal to .gitignore?

[hanjoosten]

Purpose of package.json

Some time ago I introduced the file package.json. stack uses hpack as a preprocessor to generate ampersand.cabal, before it internally uses cabal to continue its build. This gives some nice features, due to the design principles of hpack:

The guiding design principles for Hpack are:

• Don't require the user to state the obvious, make sensible assumptions by
  default
• Give the user 100% control when needed
• Don't require the user to repeat things, facilitate DRYness

A specific interesting feature for us is the fact that we can use the more liberal use of wildcards in the datafiles that we want to include.

stack will not generate ampersand.cabal if that file has been modified manually. It will then tell you to delete it, if you wish to have a generated ampersand.cabal file.

Purpose of leaving ampersand.cabal in the repo

In some cases, we do not want to use stack to build ampersand. This is (was?) the case for building for windows at AppVeyor. However, this is still under investigation, because currently the build in AppVeyor is broken. There are some issues with cabal see this and this issue. The point is that we want to be able to build on windows while keeping the git version information available. I haven't been able to get this working at AppVeyor using stack. Untill that works, we leave ampersand.cabal in the repo.

[stefjoosten]

@hanjoosten Any comments on @Michiel-s 's commit 3c55e87?

[hanjoosten]

It is nice to have a recent version of ampersand.cabal in the repo. However, it could easily lead to merge conflicts. Be assured that it is always possible to delete ampersand.cabal and have stack generate a fresh one.

[Michiel-s]

I run into merge conflicts quickly. If we can remove the ampersand.cabal file from the repo please do so. But than also add it so the gitignore.
In the other situation when I build the Ampersand compiler I first remove the cabal file so it’s generated again. Any changes can be checked in right?

[hanjoosten]

Since the build in appveyour is broken anyway, I have no problem to add ampersand.cabal to gitignore for the time being. This might change back then later.

[hanjoosten]

Recently there was a change in recomendation: Now it is recomended to check in the .cabal file into the repo, despite the merge conflicts.
A nice blog post with the motivation exists.
Core is the focus on reproducability. I think that in the case of Ampersand, that is not too much of an issue. I think that until we get bitten we can continue to .gitignore ampersand.cabal .

[hanjoosten]

Today, while trying to get an automatic windows build, I got bitten by the fact that we have ampersand.cabal in our .gitignore. Following the recomendation (see commercialhaskell/stack#5210 ), I decided to remove it from .gitignore.