1# Contributing to aptly 2 3:+1::tada: First off, thanks for taking the time to contribute! :tada::+1: 4 5The following is a set of guidelines for contributing to [aptly](https://github.com/smira/aplty) and related repositories, which are hosted in the [aptly-dev Organization](https://github.com/aptly-dev) on GitHub. 6These are just guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. 7 8## What should I know before I get started? 9 10### Code of Conduct 11 12This project adheres to the Contributor Covenant [code of conduct](CODE_OF_CONDUCT.md). 13By participating, you are expected to uphold this code. 14Please report unacceptable behavior to [team@aptly.info](mailto:team@aptly.info). 15 16### List of Repositories 17 18* [aptly-dev/aptly](https://github.com/aptly-dev/aptly) - aptly source code, functional tests, man page 19* [apty-dev/aptly-dev.github.io](https://github.com/aptly-dev/aptly-dev.github.io) - aptly website (https://www.aptly.info/) 20* [aptly-dev/aptly-fixture-db](https://github.com/aptly-dev/aptly-fixture-db) & [aptly-dev/aptly-fixture-pool](https://github.com/aptly-dev/aptly-fixture-pool) provide 21 fixtures for aptly functional tests 22 23## How Can I Contribute? 24 25### Reporting Bugs 26 271. Please search for similar bug report in [issue tracker](https://github.com/aptly-dev/aptly/issues) 282. Please verify that bug is not fixed in latest aptly nightly ([download information](https://www.aptly.info/download/)) 293. Steps to reproduce increases chances for bug to be fixed quickly. If possible, submit PR with new functional test which fails. 304. If bug is reproducible with specific package, please provide link to package file. 315. Open issue at [GitHub](https://github.com/aptly-dev/aptly/issues) 32 33### Suggesting Enhancements 34 351. Please search [issue tracker](https://github.com/aptly-dev/aptly/issues) for similar feature requests. 362. Describe why enhancement is important to you. 373. Include any additional details or implementation details. 38 39### Improving Documentation 40 41There are two kinds of documentation: 42 43* [aptly website](https://www.aptly/info) 44* aptly `man` page 45 46Core content is mostly the same, but website contains more information, tutorials, examples. 47 48If you want to update `man` page, please open PR to [main aptly repo](https://github.com/aptly-dev/aptly), 49details in [man page](#man-page) section. 50 51If you want to update website, please follow steps below: 52 531. Install [hugo](http://gohugo.io/) 542. Fork [website source](https://github.com/aptly-dev/aptly-dev.github.io) and clone it 553. Launch hugo in development mode: `hugo -w server` 564. Navigate to `http://localhost:1313/`: you should see aptly website 575. Update documentation, most of the time editing Markdown is all you need. 586. Page in browser should reload automatically as you make changes to source files. 59 60We're always looking for new contributions to [FAQ](https://www.aptly.info/doc/faq/), [tutorials](https://www.aptly.info/tutorial/), 61general fixes, clarifications, misspellings, grammar mistakes! 62 63### Your First Code Contribution 64 65Please follow [next section](#development-setup) on development process. When change is ready, please submit PR 66following [PR template](.github/PULL_REQUEST_TEMPLATE.md). 67 68Make sure that purpose of your change is clear, all the tests and checks pass, and all new code is covered with tests 69if that is possible. 70 71## Development Setup 72 73This section describes local setup to start contributing to aptly source. 74 75### Go & Python 76 77You would need `Go` (latest version is recommended) and `Python` 2.7.x (3.x is not supported yet). 78 79If you're new to Go, follow [getting started guide](https://golang.org/doc/install) to install it and perform 80initial setup. With Go 1.8+, default `$GOPATH` is `$HOME/go`, so rest of this document assumes that. 81 82Usually `$GOPATH/bin` is appended to your `$PATH` to make it easier to run built binaries, but you might choose 83to prepend it or to skip this test if you're security conscious. 84 85### Forking and Cloning 86 87As Go is using repository path in import paths, it's better to clone aptly repo (not your fork) at default location: 88 89 mkdir -p ~/go/src/github.com/aptly-dev 90 cd ~/go/src/github.com/aptly-dev 91 git clone git@github.com:aptly-dev/aptly.git 92 cd aptly 93 94For main repo under your GitHub user and add it as another Git remote: 95 96 git remote add <user> git@github.com:<user>/aptly.git 97 98That way you can continue to build project as is (you don't need to adjust import paths), but you would need 99to specify your remote name when pushing branches: 100 101 git push <user> <your-branch> 102 103### Dependencies 104 105You would need some additional tools and Python virtual environment to run tests and checks, install them with: 106 107 make prepare dev system/env 108 109This is usually one-time action. 110 111### Building 112 113If you want to build aptly binary from your current source tree, run: 114 115 make install 116 117This would build `aptly` in `$GOPATH/bin`, so depending on your `$PATH`, you should be able to run it immediately with: 118 119 aptly 120 121Or, if it's not on your path: 122 123 ~/go/bin/aptly 124 125### Unit-tests 126 127aptly has two kinds of tests: unit-tests and functional (system) tests. Functional tests are preferred way to test any 128feature, but some features are much easier to test with unit-tests (e.g. algorithms, failure scenarios, ...) 129 130aptly is using standard Go unit-test infrastructure plus [gocheck](http://labix.org/gocheck). Run the unit-tests with: 131 132 make test 133 134### Functional Tests 135 136Functional tests are implemented in Python, and they use custom test runner which is similar to Python unit-test 137runner. Most of the tests start with clean aptly state, run some aptly commands to prepare environment, and finally 138run some aptly commands capturing output, exit code, checking any additional files being created and so on. API tests 139are a bit different, as they re-use same aptly process serving API requests. 140 141The easiest way to run functional tests is to use `make`: 142 143 make system-test 144 145This would check all the dependencies and run all the tests. Some tests (S3, Swift) require access credentials to 146be set up in the environment. For example, it needs AWS credentials to run S3 tests (they would be used to publish to S3). 147If credentials are missing, tests would be skipped. 148 149You can also run subset of tests manually: 150 151 system/run.py t04_mirror 152 153This would run all the mirroring tests under `system/t04_mirror` folder. 154 155Or you can run tests by test name mask: 156 157 system/run.py UpdateMirror* 158 159Or, you can run specific test by name: 160 161 system/run.py UpdateMirror7Test 162 163Test runner can update expected output instead of failing on mismatch (this is especially useful while 164working on new tests): 165 166 system/run.py --capture <test> 167 168Output for some tests might contain environment-specific things, e.g. your home directory. In that case 169you can use `${HOME}` and similar variable expansion in expected output files. 170 171Some tests depend on fixtures, for example pre-populated GPG trusted keys. There are also test fixtures 172captured after mirror update which contain pre-build aptly database and pool contents. They're useful if you 173don't want to waste time in the test on populating aptly database while you need some packages to work with. 174There are some packages available under `system/files/` directory which are used to build contents of local repos. 175 176*WARNING*: tests are running under current `$HOME` directory with aptly default settings, so they clear completely 177`~/.aptly.conf` and `~/.aptly` subdirectory between the runs. So it's not wise to have non-dev aptly being used with 178this default location. You can run aptly under different user or by using non-default config location with non-default 179aptly root directory. 180 181### Style Checks 182 183Style checks could be run with: 184 185 make check 186 187aptly is using [golangci-lint](https://github.com/golangci/golangci-lint) to run style checks on Go code. Configuration 188for the linter could be found in [.golangci.yml](.golangci.yml) file. 189 190Python code (system tests) are linted with [flake8 tool](https://pypi.python.org/pypi/flake8). 191 192### Vendored Code 193 194aptly is using Go vendoring for all the libraries aptly depends upon. `vendor/` directory is checked into the source 195repository to avoid any problems if source repositories go away. Go build process will automatically prefer vendored 196packages over packages in `$GOPATH`. 197 198If you want to update vendored dependencies or to introduce new dependency, use [dep tool](https://github.com/golang/dep). 199Usually all you need is `dep ensure` or `dep ensure -update`. 200 201### man Page 202 203aptly is using combination of [Go templates](http://godoc.org/text/template) and automatically generated text to build `aptly.1` man page. If either source 204template [man/aptly.1.ronn.tmpl](man/aptly.1.ronn.tmpl) is changed or any command help is changed, run `make man` to regenerate 205final rendered man page [man/aptly.1](man/aptly.1). In the end of the build, new man page is displayed for visual 206verification. 207 208Man page is built with small helper [\_man/gen.go](man/gen.go) which pulls in template, command-line help from [cmd/](cmd/) folder 209and runs that through [forked copy](https://github.com/smira/ronn) of [ronn](https://github.com/rtomayko/ronn). 210 211### Bash and Zsh Completion 212 213Bash and Zsh completion for aptly reside in the same repo under in [completion.d/aptly](completion.d/aptly) and 214[completion.d/\_aptly](completion.d/_aptly), respectively. It's all hand-crafted. 215When new option or command is introduced, bash completion should be updated to reflect that change. 216 217When aptly package is being built, it automatically pulls bash completion and man page into the package. 218 219## Design 220 221This section requires future work. 222 223*TBD* 224 225### Database 226 227### Package Pool 228 229### Package 230 231### PackageList, PackageRefList 232 233### LocalRepo, RemoteRepo, Snapshot 234 235### PublishedRepository 236 237### Context 238 239### Collections, CollectionFactory 240