Skip to content

Commit 461a297

Browse files
tamalsahatamalsaha
authored
Add dev docs. (#9)
1 parent a5c5d4f commit 461a297

File tree

6 files changed

+273
-8
lines changed

6 files changed

+273
-8
lines changed

‎CONTRIBUTING.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# How to Contribute
2+
3+
AppsCode projects are [Apache 2.0 licensed](LICENSE) and accept contributions via
4+
GitHub pull requests. This document outlines some of the conventions on
5+
development workflow, commit message formatting, contact points and other
6+
resources to make it easier to get your contribution accepted.
7+
8+
## Certificate of Origin
9+
10+
By contributing to this project you agree to the Developer Certificate of
11+
Origin (DCO). This document was created by the Linux Kernel community and is a
12+
simple statement that you, as a contributor, have the legal right to make the
13+
contribution. See the [DCO](DCO) file for details.
14+
15+
## Developer Guide
16+
We have a [Developer Guide](/docs/developer-guide/README.md) that outlines everything you need to know from setting up your
17+
dev environment to how to build and test OSM. If you find something undocumented or incorrect along the way,
18+
please feel free to send a Pull Request.
19+
20+
## Getting Help
21+
If you have a question about OSM or having problem using it, you can contact us on our public Slack channel. Follow [this link](https://slack.appscode.com) to get invitation to our Slack channel.
22+
23+
## Bugs/Feature request
24+
If you have found a bug with OSM or want to request for new features, please [file an issue](https://github.com/appscode/OSM/issues/new). Be sure to describe
25+
- How can it be reproduced?
26+
- What did you expect?
27+
- What actually occurred?
28+
- Cloud provider, Go version, platform, etc. if possibly relevant.
29+
30+
31+
## Contribution Flow
32+
If you fix a bug or developed a new feature, feel free to submit a PR. In either case, please file a [Github issue]((https://github.com/appscode/osm/issues/new)) first, so that we can have a discussion on it. This is a rough outline of what a contributor's workflow looks like:
33+
34+
- Create a topic branch from where you want to base your work (usually master).
35+
- Make commits of logical units.
36+
- Push your changes to a topic branch in your fork of the repository.
37+
- Make sure the tests pass, and add any new tests as appropriate.
38+
- Submit a pull request to the original repository.
39+
40+
Thanks for your contributions!
41+
42+
## Spread the word
43+
If you have written blog post or tutorial on OSM, please share it with us on [Twitter](https://twitter.com/AppsCodeHQ) or [Slack](https://slack.appscode.com).

‎DCO‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
Developer Certificate of Origin
2+
Version 1.1
3+
4+
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
5+
660 York Street, Suite 102,
6+
San Francisco, CA 94110 USA
7+
8+
Everyone is permitted to copy and distribute verbatim copies of this
9+
license document, but changing it is not allowed.
10+
11+
12+
Developer's Certificate of Origin 1.1
13+
14+
By making a contribution to this project, I certify that:
15+
16+
(a) The contribution was created in whole or in part by me and I
17+
have the right to submit it under the open source license
18+
indicated in the file; or
19+
20+
(b) The contribution is based upon previous work that, to the best
21+
of my knowledge, is covered under an appropriate open source
22+
license and I have the right under that license to submit that
23+
work with modifications, whether created in whole or in part
24+
by me, under the same open source license (unless I am
25+
permitted to submit under a different license), as indicated
26+
in the file; or
27+
28+
(c) The contribution was provided directly to me by some other
29+
person who certified (a), (b) or (c) and I have not modified
30+
it.
31+
32+
(d) I understand and agree that this project and the contribution
33+
are public and that a record of the contribution (including all
34+
personal information I submit with it, including my sign-off) is
35+
maintained indefinitely and may be redistributed consistent with
36+
this project or the open source license(s) involved.

‎README.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
[![Go Report Card](https://goreportcard.com/badge/github.com/appscode/osm)](https://goreportcard.com/report/github.com/appscode/osm)
22

3-
[Website](https://appscode.com) • [Slack](https://slack.appscode.com) • [Twitter](https://twitter.com/AppsCodeHQ)
4-
53
# osm
64
Object Store Manipulator (osm: pronounced like `awesome`) - `curl` for cloud storage services. 🙌 `osm` can create & delete buckets and upload, download & delete files from buckets for AWS S3, Google Cloud Storage, Microsoft Azure storage and OpenStack Swift. Its single binary can be easily packaged instead of official python based clis inside Docker images.
75

@@ -99,9 +97,11 @@ osm rm -c mybucket a/b/c.pdf
9997
osm rc -f mybucket
10098
```
10199

102-
## Issues
103-
Please file an issue if you think you've found a bug. Be sure to describe
104-
* How can it be reproduced?
105-
* What did you expect?
106-
* What actually occurred?
107-
* Cloud provider, Go version, platform, etc. if possibly relevant.
100+
## Contribution guidelines
101+
Want to help improve OSM? Please start [here](/CONTRIBUTING.md).
102+
103+
## Support
104+
If you have any questions, you can reach out to us.
105+
* [Slack](https://slack.appscode.com)
106+
* [Twitter](https://twitter.com/AppsCodeHQ)
107+
* [Website](https://appscode.com)

‎docs/README.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
[![Go Report Card](https://goreportcard.com/badge/github.com/appscode/osm)](https://goreportcard.com/report/github.com/appscode/osm)
2+
3+
# osm
4+
Object Store Manipulator (osm: pronounced like `awesome`) - `curl` for cloud storage services. 🙌 `osm` can create & delete buckets and upload, download & delete files from buckets for AWS S3, Google Cloud Storage, Microsoft Azure storage and OpenStack Swift. Its single binary can be easily packaged instead of official python based clis inside Docker images.
5+
6+
## Install OSM
7+
You can download and install a pre-built binary:
8+
```console
9+
# Linux amd 64-bit:
10+
wget -O osm https://cdn.appscode.com/binaries/osm/0.5.1/osm-linux-amd64 \
11+
&& chmod +x osm \
12+
&& sudo mv osm /usr/local/bin/
13+
14+
# Linux 386 32-bit:
15+
wget -O osm https://cdn.appscode.com/binaries/osm/0.5.1/osm-linux-386 \
16+
&& chmod +x osm \
17+
&& sudo mv osm /usr/local/bin/
18+
19+
# Mac 64-bit
20+
wget -O osm https://cdn.appscode.com/binaries/osm/0.5.1/osm-darwin-amd64 \
21+
&& chmod +x osm \
22+
&& sudo mv osm /usr/local/bin/
23+
24+
# Mac 32-bit
25+
wget -O osm https://cdn.appscode.com/binaries/osm/0.5.1/osm-darwin-386 \
26+
&& chmod +x osm \
27+
&& sudo mv osm /usr/local/bin/
28+
```
29+
30+
To build from source, run: `go get -u github.com/appscode/osm`
31+
32+
## Usage
33+
```console
34+
osm [command] [flags]
35+
osm [command]
36+
37+
Available Commands:
38+
config OSM configuration
39+
help Help about any command
40+
ls List container
41+
mc Make container
42+
pull Pull item from container
43+
push Push item from container
44+
rc Remove container
45+
rm Remove item from container
46+
stat Stat item from container
47+
version Prints binary version number.
48+
49+
Flags:
50+
--alsologtostderr log to standard error as well as files
51+
--log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0)
52+
--log_dir string If non-empty, write log files in this directory
53+
--logtostderr log to standard error instead of files
54+
--stderrthreshold severity logs at or above this threshold go to stderr (default 2)
55+
-v, --v Level log level for V logs
56+
--vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging
57+
58+
Use "osm [command] --help" for more information about a command.
59+
60+
```
61+
62+
### OSM Configuration
63+
`osm` stores credentials necessary to connect to a cloud storage provider in YAML format in `$HOME/.osm/config` file.
64+
This allows providing commands one time for multiple subsequent operations with a cloud provider.
65+
```console
66+
# AWS S3:
67+
osm config set-context osm-s3 --provider=s3 --s3.access_key_id=<key_id> --s3.secret_key=<secret_key> --s3.region=us-east-1
68+
69+
# Google Cloud Storage:
70+
osm config set-context osm-gs --provider=google --google.json_key_path=<path_sa_file> --google.project_id=<my_project>
71+
72+
# Microsoft Azure ARM Storage:
73+
osm config set-context osm-az --provider=azure --azure.account=<storage_ac> --azure.key=<key>
74+
```
75+
76+
### Bucket Operations
77+
```console
78+
# create bucket
79+
osm mc mybucket
80+
81+
# upload file to bucket
82+
osm push -c mybucket ~/Downloads/appscode.pdf a/b/c.pdf
83+
84+
# print uploaded file attributes
85+
osm stat -c mybucket a/b/c.pdf
86+
87+
# download file from bucket
88+
osm pull -c mybucket a/b/c.pdf /tmp/d.pdf
89+
90+
# list bucket
91+
osm ls mybucket
92+
93+
# remove file from bucket
94+
osm rm -c mybucket a/b/c.pdf
95+
96+
# remove bucket (use -f to delete any files inside)
97+
osm rc -f mybucket
98+
```
99+
100+
## Contribution guidelines
101+
Want to help improve OSM? Please start [here](/CONTRIBUTING.md).
102+
103+
## Support
104+
If you have any questions, you can reach out to us.
105+
* [Slack](https://slack.appscode.com)
106+
* [Twitter](https://twitter.com/AppsCodeHQ)
107+
* [Website](https://appscode.com)

‎docs/developer-guide/README.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
## Development Guide
2+
This document is intended to be the canonical source of truth for things like supported toolchain versions for building OSM.
3+
If you find a requirement that this doc does not capture, please submit an issue on github.
4+
5+
This document is intended to be relative to the branch in which it is found. It is guaranteed that requirements will change over time
6+
for the development branch, but release branches of OSM should not change.
7+
8+
### Build OSM
9+
Some of the OSM development helper scripts rely on a fairly up-to-date GNU tools environment, so most recent Linux distros should
10+
work just fine out-of-the-box.
11+
12+
#### Setup GO
13+
OSM is written in Google's GO programming language. Currently, OSM is developed and tested on **go 1.8.3**. If you haven't set up a GO
14+
development environment, please follow [these instructions](https://golang.org/doc/code.html) to install GO.
15+
16+
#### Download Source
17+
18+
```console
19+
$ go get github.com/appscode/osm
20+
$ cd $(go env GOPATH)/src/github.com/appscode/osm
21+
```
22+
23+
#### Install Dev tools
24+
To install various dev tools for OSM, run the following command:
25+
26+
```console
27+
# setting up dependencies for compiling osm...
28+
$ ./hack/builddeps.sh
29+
```
30+
31+
#### Build Binary
32+
```
33+
$ ./hack/make.py
34+
$ osm version
35+
```
36+
37+
#### Dependency management
38+
OSM uses [Glide](https://github.com/Masterminds/glide) to manage dependencies. Dependencies are already checked in the `vendor` folder.
39+
If you want to update/add dependencies, run:
40+
```console
41+
$ glide slow
42+
```
43+
44+
#### Build Docker images
45+
To build and push your custom Docker image, follow the steps below. To release a new version of OSM, please follow the [release guide](/docs/developer-guide/release.md).
46+
47+
```console
48+
# Build Docker image
49+
$ ./hack/docker/osm/setup.sh; ./hack/docker/osm/setup.sh push
50+
51+
# Add docker tag for your repository
52+
$ docker tag appscode/osm:<tag> <image>:<tag>
53+
54+
# Push Image
55+
$ docker push <image>:<tag>
56+
```
57+
58+
#### Generate CLI Reference Docs
59+
```console
60+
$ ./hack/gendocs/make.sh
61+
```

‎docs/developer-guide/release.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Release Process
2+
3+
The following steps must be done from a Linux x64 bit machine.
4+
5+
- Do a global replacement of tags so that docs point to the next release.
6+
- Push changes to the `release-x` branch and apply new tag.
7+
- Push all the changes to remote repo.
8+
- Now, first build all the binaries:
9+
```console
10+
$ cd ~/go/src/github.com/appscode/osm
11+
$ ./hack/make.py build; env APPSCODE_ENV=prod ./hack/make.py push; ./hack/make.py push
12+
```
13+
- Build and push osm docker image
14+
```console
15+
$ ./hack/docker/setup.sh; env APPSCODE_ENV=prod ./hack/docker/setup.sh release
16+
```
17+
18+
Now, update the release notes in Github. See previous release notes to get an idea what to include there.

0 commit comments

Comments
 (0)