diff --git a/docs/developer_guide/CONTRIBUTING.md b/docs/developer_guide/CONTRIBUTING.md new file mode 100644 index 0000000..84e8f3c --- /dev/null +++ b/docs/developer_guide/CONTRIBUTING.md @@ -0,0 +1,135 @@ +# Getting Started + +## Fork Repository + +[Fork](https://github.com/project-stacker/stacker) the stacker repository on GitHub to your personal account. + +``` +#Set golang environment +export GOPATH=$HOME/go +mkdir -p $GOPATH/src/github.com/project-stacker + +#Get code +go get github.com/project-stacker/stacker +cd $GOPATH/src/github.com/project-stacker/stacker + +#Track repository under your personal account +git config push.default nothing # Anything to avoid pushing to project-stacker/stacker by default +git remote rename origin project-stacker +git remote add $USER git@github.com:$USER/stacker.git +git fetch $USER + +``` + +NOTES: Note that GOPATH can be any directory, the example above uses $HOME/go. +Change $USER above to your own GitHub username. + +## Build + +See [build instructions](./building_stacker.md) in the `stacker` Developer Guide. + +## Using host's toolchain + +``` +make +``` + +# Project Structure +``` +. +... +├── atomfs # Source code contains the main atomfs logic +├── cmd # Source code that handles commandline logic +├── container # Source code for container management +├── embed-exec # Source code for converting a file to a exec cmd +├── lib # Source code contains helper routines +├── log # Source code that handles logging +├── mount # Source code that handles the mount logic +├── mtree # Source code that handles the mtree logic +├── oci # Source code that handles the OCI layout logic +├── overlay # Source code that handles overlayfs logic +├── squashfs # Source code that handles squashfs logic +├── storage # Source code contains common storage code +├── test # Source code various unit tests +├── types # Source code that handles various object types + +``` + +## Contribute Workflow + +PRs are always welcome, even if they only contain small fixes like typos or a few +lines of code. If there will be a significant effort, please document it as an +issue and get a discussion going before starting to work on it. + +Please submit a PR broken down into small changes bit by bit. A PR consisting of +a lot features and code changes may be hard to review. It is recommended to +submit PRs in an incremental fashion. + +Note: If you split your pull request to small changes, please make sure any of +the changes goes to master will not break anything. Otherwise, it can not be +merged until this feature complete. + +## Develop, Build and Test + +Write code on the new branch in your fork. The coding style used in stacker is +suggested by the Golang community. See the [style doc](https://github.com/golang/go/wiki/CodeReviewComments) for details. + +Try to limit column width to 120 characters for both code and markdown documents +such as this one. + +As we are enforcing standards set by +[golangci-lint](https://github.com/golangci/golangci-lint), please always run a full 'make' on source +code before committing your changes. This will trigger compilation, unit tests +and linting. If it reports an issue, in general, the preferred action is to fix +the code. We try to enforce the guideline that code coverage doesn't drop as +code is added or modified. + +## Automated Testing (via CI/CD) + +Once your pull request has been opened, stacker will start a full CI pipeline +against it that compiles, and runs unit tests and linters. + +## Reporting issues + +It is a great way to contribute to stacker by reporting an issue. Well-written +and complete bug reports are always welcome! Please open an issue on Github and +follow the template to fill in required information. + +Before opening any issue, please look up the existing issues to avoid submitting +a duplication. If you find a match, you can "subscribe" to it to get notified on +updates. If you have additional helpful information about the issue, please +leave a comment. + +When reporting issues, always include: + +Build environment (golang compiler, etc) +Configuration files of stacker + +Log files as per configuration. + +Because the issues are open to the public, when submitting the log +and configuration files, be sure to remove any sensitive +information, e.g. user name, password, IP address, and company name. +You can replace those parts with "REDACTED" or other strings like +"****". + +Be sure to include the steps to reproduce the problem if applicable. +It can help us understand and fix your issue faster. + +## Documenting + +Update the documentation if you are creating or changing features. Good +documentation is as important as the code itself. + +The main location for the documentation is the website repository. The images +referred to in documents can be placed in docs/img in that repo. + +Documents are written with Markdown. See Writing on GitHub for more details. + +## Design New Features + +You can propose new designs for existing stacker features. You can also design +entirely new features, Please submit a proposal in GitHub issues. stacker +maintainers will review this proposal as soon as possible. This is necessary to +ensure the overall architecture is consistent and to avoid duplicated work in +the roadmap. diff --git a/docs/developer_guide/code_structure.md b/docs/developer_guide/code_structure.md index e69de29..68b1e9a 100644 --- a/docs/developer_guide/code_structure.md +++ b/docs/developer_guide/code_structure.md @@ -0,0 +1,21 @@ +# Project Structure + +``` +. +... +├── atomfs # Source code contains the main atomfs logic +├── cmd # Source code that handles commandline logic +├── container # Source code for container management +├── embed-exec # Source code for converting a file to a exec cmd +├── lib # Source code contains helper routines +├── log # Source code that handles logging +├── mount # Source code that handles the mount logic +├── mtree # Source code that handles the mtree logic +├── oci # Source code that handles the OCI layout logic +├── overlay # Source code that handles overlayfs logic +├── squashfs # Source code that handles squashfs logic +├── storage # Source code contains common storage code +├── test # Source code various unit tests +├── types # Source code that handles various object types + +```