Suggestion to add devcontainer configuration

[hsloot]

Summary

The project might benefit from providing Github's Codespaces or vscode's devcontainers configurations to allow contributors to use a Docker-based dev environment. I have a branch with a draft version, but it would require some polishing and considerations; see https://github.com/hsloot/latexindent.pl/tree/add-devcontainer. In my view, the main benefit would be that it makes it easy for inexperienced contributors (latex users but are inexperienced with Perl) to test small changes before creating PRs or debug their code when PR checks fail.

Considerations

• Align the devcontainer image with the already existing Docker image created for using latexindent?
• Align with the test workflow for pull requests such that the test workflow passes if the tests run successfully in a new devcontainer instance?

TODOs

• Provide documentation.
• Improve documentation about building and testing.
• Adjust Dockerfile to already install all required Perl modules.

[cmhughes]

Many thanks, this sounds good, please feel encouraged to take it on.

@eggplants any input/advice?

[hsloot]

I created the draft PR #443; consider trying it (e.g., in Codespaces or locally with vscode) to provide some feedback and whether all usual features for development are present.

Some comments:

• I extended the README's testing section as it requires copying some files to /usr/local/bin (I used the test workflow as a template).
• I also added a note about using the devcontainer to the README.
• The cruft directory tests fail since ~/Desktop/tmp does not exist in this devcontainer. I used $(mktemp -d) instead.
• The Dockerfile ./.devcontainer/Dockerfile is based on ./Dockerfilewith three changes: I reduced it to the base image and the apt-get command, I added locale configuration, and I installed the required Perl modules similar to the helper script.

[cmhughes]

Many thanks. I'm going to need full, detailed instructions on how to test this, please. I haven't used these tools before, so please walk me through how to do it.

…

On Tue, 2 May 2023, 23:11 Henrik Sloot, ***@***.***> wrote: I created the draft PR #443 <#443>; consider trying it (e.g., in Codespaces or locally with vscode) to provide some feedback and whether all usual features for development are present. Some comments: - I extended the README's testing section as it requires copying some files to /usr/local/bin (I used the test workflow as a template). - I also added a note about using the devcontainer to the README. - The cruft directory tests fail since ~/Desktop/tmp does not exist in this devcontainer. I used $(mktemp -d) instead. — Reply to this email directly, view it on GitHub <#442 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAQ7CYH3SVZP5UXBOUXF5TTXEGBAPANCNFSM6AAAAAAXTEZQMU> . You are receiving this because you commented.Message ID: ***@***.***>

[hsloot]

There are three options to use this:

• Github Codespaces essentially lets you code in your web browser in a remote development container hosted by GIthub. The primary interface is a version of vscode (which supports opening integrated terminals). A general overview is https://github.com/features/codespaces, which also features a GIF showing how to open a codespace from a repository. Codespace is not free but has a free monthly contingent. Similar to private actions, you should have a default spending limit of 0$, which you can check in the billing information in your settings, such that you can use the feature until your free minutes are gone. Do not forget to stop your instance once you stop using it to save your free minutes; you can manage your instances on http://github.com/codespaces.
• Using development container in vscode is a local alternative to Github Codespace. You can find a tutorial here https://code.visualstudio.com/docs/devcontainers/tutorial. It requires vscode and a running Docker instance. Have a look at the tutorial, but tldr is: Open the project in vscode, open the command palette, and run "Dev Containers: Rebuild and Reopen in Container".
• You can also use vscode as an interface to codespaces; however, this seems more or less equivalent with the browser options for all functional aspects.

The point-of-entry should be my feature branch https://github.com/hsloot/latexindent.pl/tree/add-devcontainer (meaning you start the Codespace from this branch on my fork or the vscode development container by checking out this branch); see screenshot below.

If you have not used vscode: it has an integrated terminal that you may use to test all your usual development workflows.

[hsloot]

I hope this helps. It would be great if you could try some of your usual development workflows (testing, local building, documentation, ...) to see if the Dockerfile must be extended such that the image contains all the required features. There is also the option to include further vscode extensions, but that is probably not necessary here ...

[cmhughes]

Thanks for this, I've finally been able to look at it, apologies for the delay.

what I've done to test it

1. as you recommended, I started from your branch at https://github.com/hsloot/latexindent.pl/tree/add-devcontainer
2. I used your screenshot as a guide, and clicked Create codespace on add-devcontainer which opened up a codespace (my first ever experience of this!)
3. I ran the following commands

chmod +x latexindent.pl
cp latexindent.pl /usr/local/bin
cp -r LatexIndent /usr/local/bin
cp defaultSettings.yaml /usr/local/bin

as follows:

4. I then navigated to the test-cases directory and ran test-cases.sh:

5. I then made a change to latexindent.pl by clicking on Explorer in the left-hand pane, and ran ./latexindent.pl from the terminal:

6. Running git diff then details the changes:

7. From here, presumably I can commit my changes into my branch...?

my feedback

I think this looks great, many thanks! I think this can be merged, and doesn't needed any more documentation than what you have done (thanks!), because (if I've understood the intention of this) this will be for a specific set of developers and it's not for users.

So, it looks ready to me, but what do you think?

[hsloot]

Great! So, I think one should be able to make commits and push when the codespace is started from a personal fork or if one needs write permissions to the directory it is linked to; see https://docs.github.com/en/codespaces/developing-in-codespaces/using-source-control-in-your-codespace#about-automatic-forking.

I also think you can merge it. However, you should keep in mind two hidden dependencies:

• I created the codespaces-Dockerfile using your Dockerfile for the docker-version of latexindent. You might want to keep those aligned if either is changed in the future. I think it would be possible to create a base Dockerfile and "stack" both of the currently existing ones on top of that.
• The Dockerfile installs the Perl dependencies manually. Hence, Dockerfile and helper scripts might also diverge if not manually aligned.

However, I do think these are minor issues (which, of course, could be fixed if you notice that something is broken). Also, both are probably not that difficult to do, but since I am not that familiar with Docker myself, I am not too sure about how to do it.

I will change the status so that you can merge it.

[cmhughes]

Great, many thanks! This is implemented as of 6288f5b

Thanks so much :)