This repository contains the sources of the packages I maintain or have maintained in the past for Chocolatey, the package manager for Windows.
Each package consists in a git submodule. Packages are thus completely independent from the others. This way, Chocolatey admins or even software vendors can pick the package they want without cloning everything and do not need to rewrite the history to only keep changes related to the package they want. Also, proceeding this way allows to merge a package history with ease thanks to git merge --allow-unrelated-histories.
You can work with this repository in two different ways. Either work with all of the packages or work with the submodule you are interested in.
All the submodules from this repository use a URL starting with [email protected], because they are intended to be used with SSH. Using SSH might however rise several issues for your use case.
- First, using SSH requires you to have an SSH account; this forces you to have a Github account in order to be able to clone.
- Second, if you want to use this repository for automation like continuous integration (CI) for example, this will require you to type in the passphrase to your SSH key if any. When updating submodules, the passphrase to the SSH key for these submodules will not be asked again and fetching content will thus fail.
This is why you might want to use https instead. Git provides a solution to rewrite source URL on the fly by altering your personal Git configuration.
git config --global url.https://github.com/wget/chocolatey.insteadOf "[email protected]:wget/chocolatey"
According to our test, if you do not use the --global argument which stores customizations to the user Git configuration file (.gitconfig), the URL of the submodules is not altered and this does not work. Since the URL match is quite long, this reduces the risks of overriding other custom parameters you might have.
Note that if you use this command, this will alter the way you commit as well. Additionally, if you want to be still able to commit using ssh, type the following command. Even if both arguments are the same, this is not a typo.
git config --global [email protected]:wget/chocolatey.pushInsteadOf "[email protected]:wget/chocolatey"
To learn more about how the git/ssh/https protocols can be used at GitHub, read this article.
If you are not familiar with advanced concepts of Git submodules, reading the chapter related to submodules from the progit2 book is recommended.
- Since adding submodules freezes the state of the submodules from the moment they were added to this repository, simply cloning will not be enough. You will need to get upstream changes for these repositories as well.
- Also, pulling changes from upstream clones by default changes from the branch called
masterinto a local branch of the same name, but the local branch will not track changes and will be in a detached HEAD state. In this case, you will need to checkout that branch in order for the local HEAD pointer to follow the remote HEAD pointer branch.
The following commands take care of these two caveats.
git clone --recursive [email protected]:wget/chocolatey-packages.git
git submodule foreach 'git checkout master'
Now, you will be able to work on these submodules and commit upstream directly from the submodule directory.
Update parent and submodules from upstream, trying to replay the committed changes still not pushed upstream at the top of your locally committed changes:
git submodule update --remote --rebase
Push changes made in submodules, then try to push changes made to this parent directory:
git push --recurse-submodules=on-demand
Simply click on the submodule folder in the Web UI, this should lead you to the URL of the submodule on Github. The workfload is as usual from there.
Please note that some packages make use of a library used as a submodule. In that case, use the following command:
git clone --recursive [email protected]:wget/chocolatey-package-<package name>.git
If you want to be able to publish changes to that library as well, either clone it as a separate repository or use the git submodules commands from above.
The packages need to be compliant with Powershell 2.0 running the .NET framework 4.0 for the following reasons:
- This is a requirement to install chocolatey.
- Powershell 2.0 is the latest version Windows Vista can support. The latter ends its extended support on 2017-04-11.
- Sysadmins often prepare Windows 7/Windows Server 2008 installation images when recent Powershell and .NET framework versions are not installed yet. These Windows versions are only bundled with Powershell 2.0 and .NET 4.0 by default. (source) Sysadmins usually do not update Powershell and .NET on these machines to make sure pieces of software developed for these particular versions will still work (often government sofware used in administrations, particularly slow to move forward).
- Windows Server (2008 and 2008 R2) will receive another 6 years support for companies paying an additional subscription. (source) The support for Windows Server 2008 and 2008 R2 will thus not end on 2020-01-14, but on 2026-01-14. Powershell 3.0 is the latest release Windows Server 2008 can support. (source)
The Chocolatey Automatic Package Updater Module does require at least Powershell 5.0.
To solve this dependency hell, you will need two machines:
- One running Windows 7 SP1 or Windows Server 2008 R2 SP1. You can install the recommended security upgrades as they are not changing the Powershell nor the .NET framework versions. To install updates faster, install the Convenience rollup update first which will update your install from 2011-02-22 to 2015-04, then run Windows Update for the remaining updates from 2015-04 to now.
- Another machine running at least Windows Powershell 5.0.
To learn more about the Windows Powershell availability, please read this article.
Launch a PowerShell prompt as Administrator.
Build the .nupkg package from the .nuspec file with
cpack
Test and install the .nupkg package with the following line.
-sourceis used to specify where to find the sources. As our package uses gpg as a dependency to check the signatures, we need to specify from where to get it (here, from the Chocolatey website)- The install must be forced (
-f) if the same version is already installed (will remove and reinstall the package from the updated.nupkg) - Test is performed in debug mode (
-d) - Being verbose (
-v) - Avoid asking for confirmation when installing the package (
--yes)
More information is available in the Chocolatey documentation.
choco install <package name> -fdv -source "'.;https://chocolatey.org/api/v2/'" --yes
Do not forget to test the uninstallation as well:
choco uninstall <package name> -dv --yes
Get your API key on your Chocolatey account page. The command you will need to type is like this one:
choco apiKey -k <uuid private key> -source https://chocolatey.org/
Push your package to moderation review:
choco push <package name><version>.nupkg -s https://chocolatey.org/
About 30 minutes later, you should receive an email revealing if the automatic tests have passed. If all tests have succeeded, the package will be ready for review and will be approved manually within 48 hours by a Chocolatey admin.
For urgent releases like CVE fixes, connect to the Chocolatey channel on Gitter and ping one of the following persons:
- Rob Reynolds (@ferventcoder), Chocolatey founder
- Gary Ewan Park (@gep13)
If you have comments to make or push requests to submit, feel free to contribute to this repository or one of its submodules. By contributing, you accept that your changes may be licensed under the following license terms.
As Apache 2 software can be included in GPLv3 projects, but GPLv3 software cannot be included in Apache projects and in order to comply with NuGet and Chocolatey licenses, this software is licensed under the terms of the Apache License 2.0.